png_conform 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8bcefecf4f13700db28e89f3ec81ad93df86ef0d5774057a3366ef9c74121169
-  data.tar.gz: bfd053fc3545d3ede27936476e8fce4d483c85e227d5eb5824e9faaa4f7c8872
+  metadata.gz: c3185c558227f8e781d2939e2c5ab3d938e23b2e316b7a4e6dc331e3833a808b
+  data.tar.gz: a34d66c41bed7ef373ee86fd6e492aaee2203c0655884e0f5bfffe8a644e5d3d
 SHA512:
-  metadata.gz: 8b16cfe85d3e17edc7dcdd5c4a7b1b9e416fd91be3825ac758bb2f95de19015cacc3c8c3301aabbac7174dc651e180930862b026a42968959539d4e1520857b6
-  data.tar.gz: c966fa4713fc24c7a4439e41ada2382814395d7be7bbe2e782fb388bf59d3f723ee5d36db5cac431c078c02b1dbdd9f517dbfa341ee0132ffee8403208185a69
+  metadata.gz: 67ffbca8b2bf76865aae2cf41596e85a3fb3a566b30ae27df8d229f66849a598c5c28bf84e1f36cee4a79d9c7a9eac6adad3ab548a7be669bcc1058709277881
+  data.tar.gz: aee8b3f744dc6f8f6e4fa7cf64077d4174e23fc0a789361f36229a2dc25ecf292eb4fe4662fce7c3b08931d0467c46786a104c91d250a66e34862e67391410f9

data/.rubocop_todo.yml

@@ -1,92 +1,63 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-01-19 08:52:09 UTC using RuboCop version 1.81.1.
+# on 2026-04-04 06:26:35 UTC using RuboCop version 1.86.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 6
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: with_first_argument, with_fixed_indentation
-Layout/ArgumentAlignment:
-  Exclude:
-    - 'lib/png_conform/commands/check_command.rb'
-    - 'lib/png_conform/services/chunk_processor.rb'
-    - 'lib/png_conform/services/profile_manager.rb'
-    - 'lib/png_conform/services/validator_pool.rb'
-
-# Offense count: 4
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyleAlignWith.
-# SupportedStylesAlignWith: either, start_of_block, start_of_line
-Layout/BlockAlignment:
-  Exclude:
-    - 'lib/png_conform/analyzers/comparison_analyzer.rb'
-    - 'lib/png_conform/analyzers/optimization_analyzer.rb'
-    - 'lib/png_conform/services/file_signature.rb'
-    - 'lib/png_conform/services/lru_cache.rb'
-
-# Offense count: 4
-# This cop supports safe autocorrection (--autocorrect).
-Layout/BlockEndNewline:
-  Exclude:
-    - 'lib/png_conform/analyzers/comparison_analyzer.rb'
-    - 'lib/png_conform/analyzers/optimization_analyzer.rb'
-    - 'lib/png_conform/services/file_signature.rb'
-    - 'lib/png_conform/services/lru_cache.rb'
-
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-Layout/ElseAlignment:
+Gemspec/RequireMFA:
   Exclude:
-    - 'lib/png_conform/services/validation_cache.rb'
+    - 'png_conform.gemspec'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyleAlignWith, Severity.
-# SupportedStylesAlignWith: keyword, variable, start_of_line
-Layout/EndAlignment:
+# Configuration parameters: AllowForAlignment, AllowBeforeTrailingComments, ForceEqualSignAlignment.
+Layout/ExtraSpacing:
   Exclude:
-    - 'lib/png_conform/services/validation_cache.rb'
+    - 'spec/png_conform/validators/ancillary/bkgd_validator_spec.rb'
 
-# Offense count: 2
+# Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
-# SupportedHashRocketStyles: key, separator, table
-# SupportedColonStyles: key, separator, table
-# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
-Layout/HashAlignment:
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: normal, indented_internal_methods
+Layout/IndentationConsistency:
   Exclude:
-    - 'lib/png_conform/services/validator_pool.rb'
+    - 'png_conform.gemspec'
 
-# Offense count: 10
+# Offense count: 6
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Width, AllowedPatterns.
-Layout/IndentationWidth:
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: aligned, indented
+Layout/LineEndStringConcatenationIndentation:
   Exclude:
-    - 'lib/png_conform/analyzers/comparison_analyzer.rb'
     - 'lib/png_conform/analyzers/optimization_analyzer.rb'
-    - 'lib/png_conform/services/file_signature.rb'
-    - 'lib/png_conform/services/lru_cache.rb'
-    - 'lib/png_conform/services/validation_cache.rb'
 
-# Offense count: 267
+# Offense count: 263
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
+# Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 3
+# Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowInHeredoc.
 Layout/TrailingWhitespace:
   Exclude:
-    - 'lib/png_conform/commands/check_command.rb'
-    - 'lib/png_conform/services/profile_manager.rb'
-    - 'lib/png_conform/services/validator_pool.rb'
+    - 'spec/png_conform/validators/ancillary/bkgd_validator_spec.rb'
+
+# Offense count: 14
+# This cop supports safe autocorrection (--autocorrect).
+Lint/AmbiguousOperatorPrecedence:
+  Exclude:
+    - 'benchmarks/lib/benchmark_runner.rb'
+    - 'benchmarks/lib/report_generator.rb'
+    - 'lib/png_conform/services/result_builder.rb'
+    - 'lib/png_conform/services/zlib_validator.rb'
+    - 'lib/png_conform/validators/critical/ihdr_validator.rb'
 
 # Offense count: 1
 Lint/BinaryOperatorWithIdenticalOperands:
@@ -102,6 +73,12 @@ Lint/DuplicateBranch:
     - 'lib/png_conform/validators/ancillary/sbit_validator.rb'
     - 'spec/pngsuite/helpers/semantic_validator.rb'
 
+# Offense count: 1
+# Configuration parameters: AllowComments, AllowEmptyLambdas.
+Lint/EmptyBlock:
+  Exclude:
+    - 'spec/png_conform/validators/ancillary/bkgd_validator_spec.rb'
+
 # Offense count: 4
 # Configuration parameters: AllowedParentClasses.
 Lint/MissingSuper:
@@ -142,6 +119,13 @@ Metrics/ParameterLists:
 Metrics/PerceivedComplexity:
   Enabled: false
 
+# Offense count: 132
+# Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
+# AllowedMethods: call
+# WaywardPredicates: infinite?, nonzero?
+Naming/PredicateMethod:
+  Enabled: false
+
 # Offense count: 1
 # Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
 # SupportedStyles: snake_case, normalcase, non_integer
@@ -156,6 +140,13 @@ Performance/CollectionLiteralInLoop:
   Exclude:
     - 'examples/advanced_usage.rb'
 
+# Offense count: 4
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Performance/MapCompact:
+  Exclude:
+    - 'benchmarks/lib/metrics_collector.rb'
+    - 'lib/png_conform/services/file_signature.rb'
+
 # Offense count: 70
 # Configuration parameters: Prefixes, AllowedPatterns.
 # Prefixes: when, with, without
@@ -187,51 +178,81 @@ RSpec/MultipleMemoizedHelpers:
   Max: 6
 
 # Offense count: 2
-# Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata.
+# This cop supports unsafe autocorrection (--autocorrect-all).
+RSpec/Output:
+  Exclude:
+    - 'spec/png_conform/validators/ancillary/bkgd_validator_spec.rb'
+
+# Offense count: 2
+# Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata, InflectorPath, EnforcedInflector.
+# SupportedInflectors: default, active_support
 RSpec/SpecFilePathFormat:
   Exclude:
     - 'spec/png_conform/bindata/chunk_structure_spec.rb'
     - 'spec/png_conform/bindata/png_file_spec.rb'
 
-# Offense count: 45
+# Offense count: 44
 # Configuration parameters: IgnoreNameless, IgnoreSymbolicNames.
 RSpec/VerifiedDoubles:
   Enabled: false
 
-# Offense count: 4
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
-# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
-# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
-# FunctionalMethods: let, let!, subject, watch
-# AllowedMethods: lambda, proc, it
-Style/BlockDelimiters:
+# Offense count: 2
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/BitwisePredicate:
   Exclude:
-    - 'lib/png_conform/analyzers/comparison_analyzer.rb'
-    - 'lib/png_conform/analyzers/optimization_analyzer.rb'
-    - 'lib/png_conform/services/file_signature.rb'
-    - 'lib/png_conform/services/lru_cache.rb'
+    - 'lib/png_conform/bindata/chunk_structure.rb'
+    - 'lib/png_conform/services/chunk_processor.rb'
 
-# Offense count: 41
+# Offense count: 2
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/ComparableBetween:
+  Exclude:
+    - 'lib/png_conform/validators/ancillary/trns_validator.rb'
+    - 'lib/png_conform/validators/base_validator.rb'
+
+# Offense count: 1
+Style/FileOpen:
+  Exclude:
+    - 'lib/png_conform/container.rb'
+
+# Offense count: 36
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: MaxUnannotatedPlaceholdersAllowed, Mode, AllowedMethods, AllowedPatterns.
 # SupportedStyles: annotated, template, unannotated
 Style/FormatStringToken:
   EnforcedStyle: unannotated
 
-# Offense count: 1
-Style/MissingRespondToMissing:
+# Offense count: 4
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/MapToSet:
   Exclude:
-    - 'lib/png_conform/cli.rb'
+    - 'lib/png_conform/analyzers/comparison_analyzer.rb'
 
 # Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/RedundantFormat:
+  Exclude:
+    - 'benchmarks/lib/report_generator.rb'
+
+# Offense count: 2
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Style/ReturnNilInPredicateMethodDefinition:
+  Exclude:
+    - 'lib/png_conform/analyzers/comparison_analyzer.rb'
+    - 'spec/pngsuite/helpers/pngcheck_parser.rb'
+
+# Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
-Style/MultilineTernaryOperator:
+# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiterals:
   Exclude:
-    - 'lib/png_conform/services/validation_cache.rb'
+    - 'png_conform.gemspec'
 
 # Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
-Style/RedundantParentheses:
+Style/SuperArguments:
   Exclude:
-    - 'lib/png_conform/services/validation_cache.rb'
+    - 'lib/png_conform/models/chunk_info.rb'
+    - 'lib/png_conform/models/validation_result.rb'

data/CONTRIBUTING.md

@@ -147,6 +147,28 @@ bundle exec rspec spec/path/to/spec_file.rb
 COVERAGE=true bundle exec rake spec
 ```
 
+### Diagnostics Goldens
+
+Every fixture under `spec/fixtures` has one structured diagnostics golden
+under `spec/fixtures/diagnostics/`. CI fails if a golden drifts.
+
+```bash
+# Targeted check: corpus spec only
+bundle exec rspec spec/structured_diagnostics/corpus_spec.rb
+
+# Full-corpus verification (non-mutating; also part of the default rake task)
+bundle exec rake diagnostics:check
+
+# Controlled regeneration (writes files)
+script/regenerate_diagnostic_goldens --write
+```
+
+Regenerate only when a rule, report or schema change is intended. After
+`--write`, review the complete `git diff spec/fixtures/diagnostics` and
+confirm every change is explained by your change, then rerun
+`bundle exec rake diagnostics:check` and commit the goldens in their own
+reviewable commit. Never edit a golden by hand.
+
 ### Writing Tests
 
 Follow these principles:

data/Gemfile

@@ -3,6 +3,10 @@
 source "https://rubygems.org"
 
 # Specify your gem's dependencies in png_conform.gemspec
+
+# LensCore main until v1 is released; replace with the
+# released constraint at freeze.
+gem "lens_core", github: "claricle/lens_core", branch: "main"
 gemspec
 
 gem "openssl", "~> 3.0"

data/README.adoc

@@ -328,6 +328,13 @@ $ png_conform check --format json image.png
 }
 ----
 ====
+.Structured diagnostics
+Every JSON and YAML report carries `schema_version` and a `diagnostics` array
+(identity, severity, kind, citation, location, message, context) from the shared
+`lens_core` contract. The legacy `errors` array is kept as a compatibility alias
+for one transition. See `docs/CLI_OPTIONS.adoc` (Structured diagnostics) for the
+full schema, a worked example and the migration notes.
+
 .YAML with errors
 [example]
 ====

data/Rakefile

@@ -7,4 +7,11 @@ require "rubocop/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+namespace :diagnostics do
+  desc "Verify checked-in diagnostics goldens without writing files"
+  task :check do
+    ruby "script/regenerate_diagnostic_goldens", "--check"
+  end
+end
+
+task default: %i[spec rubocop diagnostics:check]

data/TODO.structured-diagnostics/00-overview.md

@@ -0,0 +1,98 @@
+# Issue #9 — Lens-family structured diagnostics
+
+Planning baseline: `origin/main` at `653abae0d16d9533a37a5d5eca40896d3b307993`.
+
+Public requirements and related work: [`png_conform#9`](https://github.com/claricle/png_conform/issues/9), [`svg_conform#100`](https://github.com/claricle/svg_conform/issues/100), [`claricle/lens_core`](https://github.com/claricle/lens_core), and [`emf#37`](https://github.com/claricle/emf/issues/37).
+
+## Plan navigation
+
+- [01 — Adopt the shared contract behind a PNG adapter](01-shared-contract.md)
+- [02 — Catalog every rule and citation](02-requirement-catalog.md)
+- [03a — Convert PNG, APNG, and service emitters](03a-png-apng-emitters.md)
+- [03b — Convert MNG and JNG emitters](03b-mng-jng-emitters.md)
+- [03c — Make orchestration format-aware](03c-format-aware-orchestration.md)
+- [04 — Unify Ruby, JSON, YAML, and text reports](04-report-migration.md)
+- [05 — Pin corpus JSON and the release gate](05-corpus-goldens.md)
+- [Progress and handoff](90-progress.md)
+
+## Problem
+
+`png_conform` currently carries diagnostics through several incompatible representations. Validators add hashes to `ValidationContext`; `ResultBuilder#add_context_messages` then forwards only each message into `ValidationResult`; and `FileAnalysis#to_h` emits a small legacy subset. That path loses chunk offsets and error types before JSON/YAML reporting, while human reporters format the reduced model independently.
+
+Issue #9 asks for the lens-family diagnostic contract: stable identity/kind, severity, a format-native location, spec or profile citation, and machine and human renderings derived from one model. The change must cover every in-scope conformance failure and pin the resulting JSON for the fixture corpus.
+
+The shared schema is not yet a landed dependency. `svg_conform` issue #100 is responsible for defining it in the new zero-dependency `claricle/lens_core` gem (`LensCore`), while the EMF conformance work in issue #37 is on an unmerged feature branch. Existing SVG API and CLI reports also differ and lose fields in adaptation, so neither current SVG shape should be copied as the canonical contract.
+
+## Scope
+
+- Consume `LensCore` from the `claricle/lens_core` git branch published by `claricle/svg_conform#100`, then move to its released dependency when v1 freezes. Do not vendor the contract.
+- Keep a PNG adapter around the shared model so byte offset, chunk type/index, field name, expected value, and actual value can be represented without forcing SVG line/column semantics.
+- Give every active or documented direct-use conformance emitter a stable requirement ID, kind, default severity, and authoritative specification/profile citation; classify reachability before including non-registry source files.
+- Carry the same diagnostic object through validation context, result building, the Ruby API, JSON/YAML, and text reporters without dropping fields.
+- Map all 47 registered format validators—28 PNG/APNG and 19 MNG/JNG—plus shared `BaseValidator` behavior and other proven active/public emitters. Cite ISO/IEC 15948 for PNG plus the MNG 1.0 and JNG specification sections for MNG/JNG findings.
+- Make the active reader/orchestrator path format-aware: recognize PNG, MNG, and JNG signatures, apply each format's own top-level header/data/terminator rules, and prove complete valid and invalid files without cross-format false findings.
+- Pin deterministic structured JSON for all 180 existing PNG fixtures and a small, licensed MNG/JNG fixture set, with a reviewable, check-only regeneration workflow.
+- Document the public Ruby and CLI schemas, compatibility behavior, location semantics, and golden update procedure.
+
+## Exclusions
+
+- Defining, copying, or vendoring a competing family-wide contract inside this repository.
+- Implementing SVG, EMF, or PostScript conformance behavior in this repository.
+- Converting CLI invocation, missing-file, dependency, or unexpected process failures into conformance findings; those remain operational errors unless the shared contract explicitly says otherwise.
+- Changing rule semantics beyond correcting the active path's PNG-only format dispatch and top-level PNG/MNG/JNG sequence checks; auto-remediation behavior, profile policy, and pngcheck-compatible exit status otherwise remain unchanged.
+- Wiring or migrating dormant code merely because it contains emitter-like methods. Card 02 classifies `lib/png_conform/pipelines/`, `Services::ZlibValidator`, `Validators::StreamingIdatValidator`, and the legacy private emitter helpers in `ValidationService`; sources with no registry, require/call, or documented direct-use public contract stay out of the migration.
+
+## Intended end state
+
+- A single immutable diagnostic value is created at the rule boundary and survives unchanged to all report formats.
+- Its serialized shape matches the landed, versioned lens-family contract and includes stable requirement identity, kind, severity, message, structured citation, and an extensible location containing PNG-native context.
+- Human output is rendered from that value; it does not reconstruct meaning from message text.
+- Public report shapes add the canonical diagnostics while compatibility aliases preserve the legacy Ruby/JSON surface for one documented transition.
+- A catalog completeness check covers every active emitter, and corpus goldens make schema, ordering, optional-field, filename, and timestamp changes review-visible.
+
+## Cross-repository prerequisites
+
+1. **Blocking contract prerequisite — `svg_conform#100`:** a reviewed commit must publish the zero-dependency `claricle/lens_core` gem on a consumable git branch, including field names, primitive/optional value rules, deterministic ordering, human-rendering boundary, extensible location/citation representation, and schema version. The png_conform dependency remains pinned to that branch until the LensCore v1 contract freezes; a released v1 is not required to begin this issue.
+2. **Non-blocking family-parity check — `emf#37`:** recheck the EMF integration once it consumes LensCore and demonstrate the same common fields and serialization rules. EMF's current feature branch is useful evidence, but it neither defines nor supplies PNG's runtime contract.
+3. PNG implementation may inventory all format rules and citations while the LensCore branch is pending, but cards 01, 03a–03c, 04, and 05 cannot be accepted against an assumed schema.
+
+## Ordering and parallelism
+
+1. Start card 02’s complete PNG/APNG/MNG/JNG inventory immediately.
+2. Complete card 01 after `svg_conform#100` satisfies the blocking prerequisite.
+3. Cards 03a and 03b depend on cards 01 and 02, and may run in parallel by validator family.
+4. Card 03c follows the shared diagnostic APIs and both emitter conversions; it owns the reader/orchestrator format dispatch and full-file PNG/MNG/JNG integration proofs.
+5. Card 04 follows cards 03a–03c so additive compatibility assertions exercise the final cross-format objects.
+6. Card 05 may source and license the small MNG/JNG fixture set early, but golden generation follows card 04; perform its single reviewed regeneration only after the schema, format dispatch, and rendering policy are frozen.
+
+## Effort
+
+| Card | Work | Estimate |
+| --- | --- | ---: |
+| 01 | Shared contract and PNG adapter | 1–2 engineer-days |
+| 02 | Requirement catalog and citation inventory | 1–2 engineer-days |
+| 03a | PNG/APNG and service emitters | 2–3 engineer-days |
+| 03b | MNG/JNG emitters | 1.5–2.5 engineer-days |
+| 03c | Format-aware readers, orchestration, and full-file integration | 1.5–2.5 engineer-days |
+| 04 | Ruby API and report migration | 1.5–2.5 engineer-days |
+| 05 | Licensed cross-format corpus, goldens, documentation, and release gate | 1.5–3 engineer-days |
+
+The required PNG/APNG/MNG/JNG scope totals **10–17.5 engineer-days**. The total excludes the external wait for the LensCore branch and assumes authoritative specification text and suitable redistributable MNG/JNG samples are available to the implementer.
+
+## Project decisions
+
+1. `claricle/lens_core` is the sole shared-contract source. png_conform consumes its git branch until v1 freezes and never vendors a local copy.
+2. PNG, APNG, MNG, and JNG are all required. All 47 registered format validators are mapped, the active validation path dispatches their distinct signatures and top-level rules, and the golden corpus gains a small licensed MNG/JNG set alongside the 180 PNG fixtures.
+3. Public report changes are additive. Compatibility aliases preserve the legacy surface for one documented transition; this issue does not perform a breaking replacement.
+
+## Planning evidence
+
+- `lib/png_conform/validators/base_validator.rb` creates context hashes with message/severity/chunk/offset.
+- `lib/png_conform/services/result_builder.rb` drops all fields except message when building results.
+- `lib/png_conform/models/validation_error.rb` lacks canonical requirement, citation, and location values.
+- `lib/png_conform/models/file_analysis.rb` defines the current machine representation; `lib/png_conform/reporters/json_reporter.rb` serializes it directly.
+- `ChunkRegistry::VALIDATOR_PATHS` has 47 registered format validators: 28 PNG/APNG and 19 MNG/JNG. `BaseValidator` is shared infrastructure outside that count; `StreamingIdatValidator` is not registered.
+- `lib/png_conform/services/profile_manager.rb` is loaded by the public library and directly exposes profile validation. `validate_chunk_against_profile` emits unknown-profile and prohibited-chunk errors plus undefined-chunk warnings; `validate_file_against_profile` emits prohibited-present and missing-required errors. Those existing semantics must enter the canonical model while their public result keys remain available during the compatibility transition.
+- `ValidationOrchestrator` currently accepts only the PNG signature and unconditionally requires `IHDR`, `IEND`, and `IDAT`. `StreamingReader` likewise recognizes only the PNG signature and stops only at `IEND`; format-specific BinData models establish MNG's `MHDR`/`MEND` envelope and JNG's `JHDR`/`JDAT`/`IEND` envelope.
+- The source tree has 317 candidate diagnostic-emission call sites before reachability filtering, 47 validator specs plus base-validator and registry specs (49 files total), 180 PNG fixtures, no MNG/JNG fixtures, and no diagnostic JSON goldens.
+- `FileAnalysis#to_h` currently emits `severity` and `message` for each error plus optional `chunk_type`, `expected`, and `actual`; `chunk_offset` and `error_type` exist as Ruby readers but are not current JSON keys.

data/TODO.structured-diagnostics/01-shared-contract.md

@@ -0,0 +1,36 @@
+# 01 — Adopt the shared contract behind a PNG adapter
+
+## Purpose
+
+Bind `png_conform` to the zero-dependency `claricle/lens_core` gem defined by `svg_conform#100` without copying SVG-only coordinates or coupling validators to package internals. Preserve the existing `ValidationError` entry points as additive compatibility aliases while making the shared diagnostic the source of truth.
+
+## Work
+
+- Declare the `lens_core` runtime dependency in `png_conform.gemspec` and pin `claricle/lens_core` to the reviewed integration branch through `Gemfile`/`Gemfile.lock` until v1 freezes. Replace the git source with the released v1 constraint at freeze; do not publish png_conform while its installable dependency is unavailable.
+- Require LensCore directly from the dependency. Do not create a vendored or locally reimplemented shared-contract module.
+- Add `lib/png_conform/diagnostics/location.rb` for PNG-native location data: byte offset plus optional chunk type, chunk index, and field. Its shared projection must use only the extension/context mechanism defined upstream.
+- Add `lib/png_conform/diagnostics/citation.rb` only if the upstream contract delegates citation construction to consumers; otherwise wrap the upstream value without changing its keys.
+- Refactor `PngConform::Models::ValidationError` to own/delegate to the shared immutable diagnostic while retaining documented severity predicates, factories, legacy readers, and `#to_s` behavior as compatibility aliases for one documented transition.
+- Add `spec/png_conform/diagnostics/shared_contract_spec.rb` to pin schema version, primitive types, optional-field policy, location projection, stable serialization, and human rendering. Extend `spec/png_conform/models/validation_error_spec.rb` for legacy compatibility.
+
+## Dependencies
+
+- Blocking: `svg_conform#100` publishes the versioned LensCore schema and a consumable `claricle/lens_core` git branch.
+- Non-blocking parity evidence: once EMF #37 consumes LensCore, its contract tests serialize the same common fields. PNG-specific location context may differ.
+
+## Done when
+
+- The dependency points to one reviewed LensCore branch revision, and no second family schema or vendored copy is defined locally.
+- A PNG diagnostic round-trips stable requirement identity, kind, severity, message, citation, and byte/chunk location using JSON-safe primitives.
+- The same object produces machine and human representations, and changing a structured field changes both applicable representations without message parsing.
+- Existing documented `ValidationError` readers and predicates remain available as compatibility aliases for the documented transition.
+
+```bash
+bundle exec rspec spec/png_conform/diagnostics/shared_contract_spec.rb \
+  spec/png_conform/models/validation_error_spec.rb
+```
+
+## Status
+
+State: done
+PR: https://github.com/claricle/png_conform/pull/14

data/TODO.structured-diagnostics/02-requirement-catalog.md

@@ -0,0 +1,37 @@
+# 02 — Catalog every rule and citation
+
+## Purpose
+
+Replace message text as the implicit rule identity with a complete, reviewable registry across PNG, APNG, MNG, and JNG. This card can begin while the upstream schema is pending.
+
+## Work
+
+- Add `config/diagnostics.yml`, keyed by stable requirement ID, with format, kind, default severity, specification/profile name and version, and exact section/clause citation. Keep messages/templates in the catalog only if the shared contract standardizes them there.
+- Add `lib/png_conform/diagnostics/catalog.rb` to load and validate the registry, reject duplicate/unknown IDs, and return typed data for diagnostic construction.
+- Inventory the 47 validators registered in `ChunkRegistry::VALIDATOR_PATHS`—28 PNG/APNG and 19 MNG/JNG—then separately inventory shared findings from `lib/png_conform/validators/base_validator.rb`, direct findings in `lib/png_conform/services/validation_orchestrator.rb` and `chunk_processor.rb`, and the public profile findings from `ProfileManager.validate_chunk_against_profile` and `ProfileManager.validate_file_against_profile` in `lib/png_conform/services/profile_manager.rb`. Inventory any other emitter only when it is proven active or covered by a documented direct-use public contract. Include active informational diagnostics in the one-model migration even though they are not failures.
+- Trace registry membership, `require` edges, call sites, public documentation, and focused direct-use tests for non-registry sources. Record an explicit include/exclude rationale for `lib/png_conform/pipelines/`, `Services::ZlibValidator`, `Validators::StreamingIdatValidator`, and the legacy private emitter helpers in `ValidationService`. Do not wire dormant classes into production or catalog unreachable helper methods just to expand coverage; a non-registry source enters scope only when a direct-use public contract is documented and tested.
+- Assign citations from ISO/IEC 15948 (including the applicable edition), the APNG specification, and the MNG 1.0 and JNG specifications. Profile-only policy findings cite the profile ID/version rather than inventing a normative PNG clause.
+- Add `spec/png_conform/diagnostics/catalog_spec.rb` to prove schema validity, unique IDs, known severities/kinds/formats, citation presence, and complete coverage of the explicit emitter inventory. The inventory must fail when a new emitter lacks a catalog ID.
+- Document non-conformance informational messages separately; do not give success/progress messages fictitious normative citations.
+
+## Dependencies
+
+- Access to the authoritative editions used for clause-level review.
+- The final serializer keys wait on card 01, but stable IDs and source citations do not.
+
+## Done when
+
+- Every active error, warning, and conformance-information path across all 47 registered validators, shared `BaseValidator` behavior, and other proven active/public emitters has one stable catalog ID and an authoritative spec/profile citation appropriate to its format.
+- The catalog distinguishes `ProfileManager.validate_chunk_against_profile` findings for an unknown profile, a prohibited chunk, and a chunk undefined by a profile from `validate_file_against_profile` findings for a prohibited-present chunk and a missing required chunk, with the applicable profile ID/version as the policy citation.
+- Common helper findings remain distinguishable by violated requirement rather than collapsing to one generic length/range/CRC ID.
+- Duplicate IDs, missing citations, unknown metadata values, and uncataloged emitters fail a focused completeness spec.
+- The inventory records a source-backed reachability/public-contract classification for `lib/png_conform/pipelines/`, `Services::ZlibValidator`, `Validators::StreamingIdatValidator`, and the legacy `ValidationService` helper emitters so card 03a has explicit inclusion decisions and no speculative migration work.
+
+```bash
+bundle exec rspec spec/png_conform/diagnostics/catalog_spec.rb
+```
+
+## Status
+
+State: done
+PR: https://github.com/claricle/png_conform/pull/13

data/TODO.structured-diagnostics/03a-png-apng-emitters.md

@@ -0,0 +1,45 @@
+# 03a — Convert PNG, APNG, and service emitters
+
+## Purpose
+
+Create the canonical diagnostic once at each active PNG/APNG rule boundary and carry it without metadata loss through the validation pipeline.
+
+## Work
+
+- Change `ValidationContext` in `lib/png_conform/validators/base_validator.rb` to collect diagnostic values instead of ad hoc hashes. Require a catalog ID at every conformance-diagnostic boundary, explicitly including informational findings; pass dynamic message data, PNG location, and expected/actual context separately.
+- Update the 28 registered non-MNG/JNG validators under `lib/png_conform/validators/critical/`, `ancillary/`, and `apng/` to emit the cataloged requirements from card 02. Convert shared `BaseValidator` behavior separately; it is infrastructure, not a 29th registered validator.
+- Convert the direct active unknown-critical findings in `lib/png_conform/services/chunk_processor.rb`, plus any other non-registry emitter that card 02 proves has a documented, tested direct-use public contract. Card 03c exclusively owns `ValidationOrchestrator` signature, missing-chunk, and top-level ordering findings so format dispatch is changed and tested as one unit.
+- Migrate the active profile-policy emitter in `lib/png_conform/services/profile_manager.rb` without changing its split responsibilities. `validate_chunk_against_profile` must construct canonical diagnostics for an unknown profile, a prohibited chunk, and a chunk undefined by the profile; `validate_file_against_profile` must construct them for prohibited-present and missing-required chunks. Preserve the former method's existing `status`/`message` keys and the latter's `valid`/`errors`/`warnings` keys as compatibility projections for the documented transition; no profile finding may remain string-only internally.
+- Keep `Services::ZlibValidator`, `Validators::StreamingIdatValidator`, and the legacy private emitter helpers in `ValidationService` out of the migration under the current source evidence: the first two have no require/call path, the streaming validator is absent from the registry, and the helper emitters are unused. Do not make them reachable as part of this issue. If card 02 finds an existing documented direct-use contract, add that source to the explicit active inventory and add a focused spec before converting it.
+- Refactor `ResultBuilder#add_context_messages` in `lib/png_conform/services/result_builder.rb` to append each diagnostic intact. Remove severity-specific reconstruction that currently retains only `e[:message]`.
+- Follow card 02’s reachability finding for `lib/png_conform/pipelines/`: adapt an emitter only if an existing public/reachable path is proven; otherwise record the directory as outside the active issue path. Do not create a second diagnostic pipeline by making dormant code reachable.
+- Extend existing validator and profile-manager specs to assert IDs, citations, severity, and applicable absolute byte/chunk locations in addition to message text. In `spec/png_conform/services/profile_manager_spec.rb`, add structured assertions for unknown-profile, prohibited-chunk, and undefined-chunk results from `validate_chunk_against_profile`, plus prohibited-present and missing-required results from `validate_file_against_profile`; keep the existing success examples as preservation checks. Card 03c owns orchestrator and full-file integration assertions.
+- Together with card 03b, make `spec/png_conform/diagnostics/emitter_coverage_spec.rb` enumerate all 47 registered validators so the agreed inventory is explicit and regression-visible.
+
+## Dependencies
+
+- Cards 01 and 02.
+- Card 03b runs in parallel after the shared context/catalog APIs are merged; both emitter cards feed card 03c and are required before card 04.
+
+## Done when
+
+- All active PNG/APNG and shared-service errors, warnings, and conformance-information messages across the 28 registered non-MNG/JNG validators originate as canonical diagnostics with catalog IDs and citations.
+- `ValidationContext` to `ResultBuilder` preserves diagnostic identity, location, expected/actual context, and severity exactly.
+- CRC, unknown-critical, registered compressed-payload, and representative critical/ancillary/APNG failures each have focused structured assertions; card 03c separately proves signature and top-level sequence findings.
+- `ProfileManager.validate_chunk_against_profile` has structured assertions for unknown-profile and prohibited-chunk errors plus an undefined-chunk warning; `ProfileManager.validate_file_against_profile` has structured prohibited-present and missing-required-chunk assertions. Every case proves stable ID, policy citation, severity, message, and the applicable profile/chunk context while preserving current compatibility keys.
+- Dormant non-registry classes and unused `ValidationService` helper emitters are neither wired into production nor counted as migrated unless their pre-existing direct-use public contract is documented and covered by a focused spec.
+- No active PNG/APNG conformance emitter bypasses the cataloged diagnostic constructor.
+
+```bash
+bundle exec rspec spec/png_conform/diagnostics/emitter_coverage_spec.rb \
+  spec/png_conform/validators/base_validator_spec.rb \
+  spec/png_conform/validators/critical \
+  spec/png_conform/validators/ancillary \
+  spec/png_conform/validators/apng \
+  spec/png_conform/services/profile_manager_spec.rb
+```
+
+## Status
+
+State: done
+PR: https://github.com/claricle/png_conform/pull/17

data/TODO.structured-diagnostics/03b-mng-jng-emitters.md

@@ -0,0 +1,34 @@
+# 03b — Convert MNG and JNG emitters
+
+## Purpose
+
+Apply the same contract to the other file formats that `png_conform` publicly advertises, using their own normative specifications rather than mislabeling their requirements as ISO/IEC 15948 rules.
+
+## Work
+
+- Update all 19 validators under `lib/png_conform/validators/mng/` and `lib/png_conform/validators/jng/` to require the stable IDs cataloged in card 02.
+- Preserve MNG/JNG byte offsets, chunk type/index, field context, expected/actual values, severity, and format in the shared location/context projection.
+- Extend the existing MNG/JNG validator specs with structured identity and citation assertions for representative length, field, sequence, and required-chunk failures.
+- Add MNG/JNG emitter coverage to `spec/png_conform/diagnostics/emitter_coverage_spec.rb` so future rules cannot silently return to message-only errors.
+
+## Dependencies
+
+- Cards 01 and 02.
+- Card 03a shares the context/catalog APIs and emitter-coverage spec; coordinate those files while converting the two required format families. Card 03c consumes both emitter cards and owns end-to-end format dispatch.
+
+## Done when
+
+- Every active MNG/JNG conformance error, warning, and information message across all 19 validators uses a stable catalog ID and the applicable MNG 1.0 or JNG specification section.
+- Representative MNG and JNG diagnostics preserve structured format, byte/chunk location, severity, and rule identity through `ValidationResult`.
+- The emitter completeness spec covers the MNG/JNG validator directories and fails on an uncataloged finding.
+
+```bash
+bundle exec rspec spec/png_conform/diagnostics/emitter_coverage_spec.rb \
+  spec/png_conform/validators/mng \
+  spec/png_conform/validators/jng
+```
+
+## Status
+
+State: done
+PR: https://github.com/claricle/png_conform/pull/16