Epic: Implement WKT decoding #4

Goal

Introduce Well-Known Text (WKT) decoding capabilities in longitude-one/spatial-decoder.

The library must provide a concrete WKT decoding strategy implementing DecodeStrategyInterface, allowing textual spatial representations to be decoded into objects implementing SpatialInterface from longitude-one/spatial-types.

The implementation must follow the public decoding API defined by spatial-decoder and comply with the applicable WKT specification.

This Epic is intended to progressively replace the decoding responsibilities currently provided by longitude-one/wkt-parser, while preserving its existing supported functionality through a controlled migration process.

Scope

The Epic covers the implementation of WKT decoding capabilities, including:

• Integration of a WKT decoding strategy into the public Decoder API.
• Decoding of the spatial geometry types supported by the target spatial object model.
• Support for applicable coordinate dimensions.
• Handling of empty geometries.
• Handling of spatial reference information when supported by the input representation.
• Validation of WKT syntax and spatial data.
• Explicit rejection of malformed or unsupported representations.
• Construction of the corresponding immutable spatial objects.
• Migration and adaptation of the existing wkt-parser unit tests.

The implementation must preserve spatial information represented by the input format and supported by the spatial object model.

Unsupported representations or dimensions must be explicitly rejected rather than silently converted or discarded.

The exact scope of each supported geometry type, coordinate dimension, and WKT representation will be defined during Story refinement.

Standards and references

The WKT decoder must comply with the following specification:

OGC Simple Feature Access — Part 1: Common Architecture, Version 1.2.1

Section 7 — Well-known Text Representation for Geometry.

Specification: https://portal.ogc.org/files/?artifact_id=25355

Any supported extensions or deviations from this specification must be explicitly documented.

Migration from wkt-parser

spatial-decoder is intended to progressively supersede longitude-one/wkt-parser.

The migration must preserve the existing supported decoding functionality while adapting it to the new public API and spatial object model.

The implementation may reuse or adapt existing parsing algorithms where appropriate.

However, the new WKT decoding strategy must not depend on longitude-one/wkt-parser as a runtime dependency.

The migration must not introduce implicit spatial transformations or preserve legacy behavior that conflicts with the applicable WKT specification without an explicit architectural decision.

Deprecation or archival of longitude-one/wkt-parser will be handled separately, once the required functionality has been migrated and validated.

Legacy unit tests

The existing unit tests from longitude-one/wkt-parser must be migrated into spatial-decoder.

These tests must be maintained in a dedicated subdirectory to distinguish them from tests written specifically for the new decoding architecture.

The proposed directory is:

tests/Legacy/WktParser/

The migration must:

• Identify and recover the existing WKT parser unit tests.
• Preserve the original test scenarios and expected decoding behavior wherever compatible with the new architecture.
• Adapt namespaces, dependencies, fixtures, and assertions to the new public decoding API.
• Preserve the identification of the original test cases to facilitate traceability.
• Explicitly document any test that cannot be migrated without modification of its original expected behavior.
• Ensure that migrated tests are executed by the standard PHPUnit test suite and CI pipeline.

The migrated tests must remain identifiable as legacy compatibility tests.

New tests covering the public Decoder API, WKT decoding strategy, normative compliance, and additional functionality must be maintained separately from the migrated legacy tests.

The legacy test suite must not be considered sufficient on its own to demonstrate compliance with the applicable WKT specification.

Testing and quality

Each Story implementing WKT decoding functionality must include appropriate unit tests covering its defined scope.

Tests must verify:

• Correct decoding of supported WKT representations.
• Correct construction of the corresponding spatial objects.
• Preservation of supported coordinate dimensions and spatial information.
• Handling of empty geometries.
• Explicit rejection of malformed or unsupported input.
• Compliance with the applicable WKT specification.
• Integration with the public Decoder API.

The migrated legacy tests must be included in the standard quality and continuous integration pipeline.

Documentation

The WKT decoding documentation must describe:

• The supported WKT representations and applicable specification.
• The supported spatial geometry types and coordinate dimensions.
• The handling of empty geometries and spatial reference information.
• The usage of the WKT decoding strategy through the public Decoder API.
• Unsupported representations and known limitations.
• The migration path from longitude-one/wkt-parser, when applicable.

Completion criteria

This Epic may be considered complete when:

• The WKT decoding strategy is integrated into the public Decoder API.
• All WKT representations included in the refined scope are supported.
• The applicable normative requirements are satisfied.
• The required legacy wkt-parser tests have been migrated and are executed by CI.
• Any excluded or intentionally modified legacy behavior is documented.
• New unit tests validate the decoding architecture and supported functionality.
• Public documentation describes the WKT decoding capabilities and limitations.
• All associated Stories have been completed and accepted.

Out of scope

• WKB decoding.
• GeoJSON decoding.
• WKT encoding or serialization.
• Coordinate Reference System reprojection.
• Implicit coordinate dimension conversion.
• Implicit geometry-type conversion.
• Modifications to the existing longitude-one/wkt-parser public API.
• Deprecation or archival of longitude-one/wkt-parser.

This Epic does not prescribe the internal parsing architecture or the number of implementation Stories. These decisions will be addressed during refinement.