Honor Table.coordinate_system and decouple bedtools-compat from interval_type in DISTANCE / NEAREST — Closes #89

[conradbzura]

Summary

Make DISTANCE and NEAREST honor Table.coordinate_system and stop conflating Table.interval_type with bedtools-style "+1" gap counting, so logically-equivalent intervals stored under different conventions yield the same numeric distance. Reuse the _canonical_start and _canonical_end helpers introduced in #88 to canonicalize all four endpoint expressions to 0-based half-open before they reach _generate_distance_case, and drop the implicit "+1" gap counting that closed-interval tables previously triggered.

This is a behavior change with no opt-in: tables declared with interval_type="closed" no longer apply the "+1" gap quirk for either DISTANCE or NEAREST, and interval_type no longer drives any gap arithmetic. Callers who relied on the legacy "+1" must add it explicitly in the consuming query (e.g. wrap the result in ... + 1). The two pre-existing bedtools-compat tests are rewritten to assert the new behavior, and parametrized regression tests cover canonicalization across all four (coordinate_system, interval_type) combinations for both operators.

Literal-form DISTANCE (still NotImplementedError) and the spatial-predicate code paths fixed in #88 are out of scope.

Closes #89

Proposed changes

src/giql/generators/base.py

• giqldistance_sql: resolve each side's Table config via _resolve_table and wrap raw start/end with _canonical_start / _canonical_end before they reach _generate_distance_case.
• giqlnearest_sql: hoist the target-Table lookup and wrap target endpoints via the helpers.
• _resolve_nearest_reference: canonicalize column-ref returns via _canonical_start / _canonical_end in all three branches — standalone column reference, correlated explicit reference, and correlated implicit reference (literal returns are already canonical via RangeParser.to_zero_based_half_open).
• _generate_distance_case: drop the add_one_for_gap parameter and the gap_adj term; the CASE expression now operates entirely in canonical 0-based half-open space.

tests/generators/test_base.py

• Rename the two pre-existing closed-interval tests to the BDD pattern and rewrite them to assert that closed-interval tables emit no +1 gap counting.
• Add parametrized canonicalization tests for DISTANCE across all four (coordinate_system, interval_type) combinations, a mixed-conventions DISTANCE test, parametrized NEAREST target-side tests, a column-ref reference NEAREST test (standalone mode), and a correlated/implicit-reference NEAREST test that exercises canonicalization of the outer table's columns.
• Tighten the NEAREST gap-counting assertions to require both gap branches to carry the expected formulas (the previous or chain would have silently passed even if only one branch were correct).

docs/transpilation/index.rst

• Note that DISTANCE/NEAREST canonicalize table-side endpoints based on their (coordinate_system, interval_type) config, and add a .. versionchanged:: directive flagging the removal of the implicit +1 gap counting.

Test cases

#	Test Suite	Given	When	Then	Coverage Target
1	TestBaseGIQLGenerator	Two 0-based closed tables joined under DISTANCE	giqldistance_sql is called	The CASE expression canonicalizes each end as (end + 1) and emits no + 1 in the gap branches	Removal of the legacy implicit "+1" in DISTANCE for closed-interval tables
2	TestBaseGIQLGenerator	A 0-based closed target table for NEAREST	giqlnearest_sql is called	The distance CASE expression canonicalizes the target end as (end + 1) and emits no + 1 in the gap branches	Removal of the legacy implicit "+1" in NEAREST for closed-interval target tables
3	TestBaseGIQLGenerator	Two tables sharing one of the four (coordinate_system, interval_type) combinations	DISTANCE is called between aliased columns from each table	Each side's start/end is wrapped per the canonical 0-based half-open conversion, leaving comparison and gap formulas otherwise unchanged	DISTANCE canonicalization across all four conventions
4	TestBaseGIQLGenerator	A 0-based half-open table joined against a 1-based closed table	DISTANCE is called between aliased columns from each table	The 1-based-closed side's start is wrapped as (start - 1), the default side stays raw, and the comparison/gap formulas use the canonicalized expressions	DISTANCE under mixed conventions
5	TestBaseGIQLGenerator	A target table declared with one of the four (coordinate_system, interval_type) combinations and a literal reference range	giqlnearest_sql is called	The distance CASE expression wraps target start/end per the canonical 0-based half-open conversion against the already-canonical literal reference	NEAREST target canonicalization across all four conventions
6	TestBaseGIQLGenerator	A 0-based half-open target table and an explicit reference column from a 1-based closed table	giqlnearest_sql is called	The reference's start is wrapped as (start - 1), the reference's end stays raw, and the target side stays raw	NEAREST reference canonicalization for column-ref references in standalone mode
7	TestBaseGIQLGenerator	A 1-based closed outer table and a 0-based half-open target table joined via CROSS JOIN LATERAL with no reference argument	giqlnearest_sql is called	The distance CASE expression wraps the outer table's start as (start - 1), leaves its end raw, and leaves the target side raw	NEAREST reference canonicalization for the correlated/implicit-reference branch