tg_geometry 0.1.0 → 0.3.0

data/spec/{block_8_index_borrowed_geometry_spec.rb → index_borrowed_geometry_spec.rb}

@@ -5,7 +5,7 @@ require "json"
 require "objspace"
 require "weakref"
 
-RSpec.describe "Release Core Block 8 Index borrowed geometry ingestion" do
+RSpec.describe "Index borrowed geometry ingestion" do
   let(:polygon_a_wkt) { "POLYGON ((0 0, 2 0, 2 2, 0 2, 0 0))" }
   let(:polygon_b_wkt) { "POLYGON ((10 10, 12 10, 12 12, 10 12, 10 10))" }
 

data/spec/{block_6_index_build_spec.rb → index_build_spec.rb}

@@ -2,7 +2,7 @@
 
 require "spec_helper"
 
-RSpec.describe "Release Core Block 6 Index build skeleton" do
+RSpec.describe "Index build" do
   let(:geom) { TG::Geometry.parse_wkt("POINT (1 2)") }
 
   it "builds an empty immutable index" do
@@ -54,7 +54,7 @@ RSpec.describe "Release Core Block 6 Index build skeleton" do
       .to raise_error(TG::Geometry::ArgumentError)
   end
 
-  it "requires String values for owned geometry modes in the block 6 skeleton" do
+  it "requires String values for owned geometry modes in the owned geometry build path" do
     expect { TG::Geometry::Index.build([[1, Object.new]], via: :geojson, strategy: :flat) }
       .to raise_error(TypeError)
     expect { TG::Geometry::Index.build([[1, Object.new]], via: :wkb, strategy: :flat) }

data/spec/{block_9_flat_query_spec.rb → index_flat_query_spec.rb}

@@ -2,7 +2,7 @@
 
 require "spec_helper"
 
-RSpec.describe "Release Core Block 9 flat query engine" do
+RSpec.describe "Flat index query engine" do
   let(:zone_a) { TG::Geometry.parse_wkt("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))") }
   let(:zone_b) { TG::Geometry.parse_wkt("POLYGON ((5 5, 12 5, 12 12, 5 12, 5 5))") }
   let(:zone_c) { TG::Geometry.parse_wkt("POLYGON ((20 20, 22 20, 22 22, 20 22, 20 20))") }

data/spec/index_geom_query_spec.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Index geometry queries" do
+  def polygon(min_x, min_y, max_x, max_y)
+    TG::Geometry.polygon([[min_x, min_y], [max_x, min_y], [max_x, max_y], [min_x, max_y], [min_x, min_y]])
+  end
+
+  let(:zones) do
+    [
+      [:a, polygon(0, 0, 10, 10)],
+      [:b, polygon(8, 8, 18, 18)],
+      [:c, polygon(30, 30, 40, 40)]
+    ]
+  end
+
+  def build(strategy)
+    TG::Geometry::Index.build(zones, via: :geom, strategy: strategy)
+  end
+
+  it "returns intersecting ids in insertion order" do
+    query = polygon(9, 9, 12, 12)
+
+    expect(build(:flat).intersecting_geom_ids(query)).to eq(%i[a b])
+    expect(build(:rtree).intersecting_geom_ids(query)).to eq(%i[a b])
+  end
+
+  it "supports line query intersections" do
+    query = TG::Geometry.line_string([[35, 35], [45, 45]])
+
+    expect(build(:flat).intersecting_geom_ids(query)).to eq([:c])
+  end
+
+  it "returns empty arrays for outside query geometries" do
+    expect(build(:rtree).intersecting_geom_ids(polygon(100, 100, 101, 101))).to eq([])
+  end
+
+  it "uses stored_geom covers query semantics" do
+    index = build(:flat)
+
+    expect(index.covering_geom_ids(TG::Geometry.point(5, 5))).to eq([:a])
+    expect(index.covering_geom_ids(TG::Geometry.point(0, 5))).to eq([:a])
+    expect(index.covering_geom_ids(polygon(9, 9, 12, 12))).to eq([:b])
+  end
+
+  it "uses stored_geom contains query semantics and excludes boundary" do
+    index = build(:flat)
+
+    expect(index.containing_geom_ids(TG::Geometry.point(5, 5))).to eq([:a])
+    expect(index.containing_geom_ids(TG::Geometry.point(0, 5))).to eq([])
+    expect(index.covering_geom_ids(TG::Geometry.point(0, 5))).to eq([:a])
+  end
+
+  it "does not read Index.build predicate for geometry methods" do
+    index = TG::Geometry::Index.build(zones, via: :geom, strategy: :flat, predicate: :contains)
+
+    expect(index.covering_geom_ids(TG::Geometry.point(0, 5))).to eq([:a])
+  end
+
+  it "raises TypeError for non-Geom query values" do
+    index = build(:flat)
+
+    expect { index.intersecting_geom_ids(nil) }.to raise_error(TypeError)
+    expect { index.covering_geom_ids("bad") }.to raise_error(TypeError)
+    expect { index.containing_geom_ids(1) }.to raise_error(TypeError)
+  end
+end

data/spec/{block_7_index_owned_geometry_spec.rb → index_owned_geometry_spec.rb}

@@ -3,7 +3,7 @@
 require "spec_helper"
 require "objspace"
 
-RSpec.describe "Release Core Block 7 Index owned geometry ingestion" do
+RSpec.describe "Index owned geometry ingestion" do
   let(:geojson_a) do
     '{"type":"Polygon","coordinates":[[[0,0],[2,0],[2,2],[0,2],[0,0]]]}'
   end

data/spec/{block_10_rtree_strategy_spec.rb → index_rtree_accounting_spec.rb}

@@ -2,7 +2,7 @@
 
 require "spec_helper"
 
-RSpec.describe "Release Core Block 10 exact rtree accounting" do
+RSpec.describe "Exact rtree accounting" do
   let(:zone_a) { TG::Geometry.parse_wkt("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))") }
   let(:zone_b) { TG::Geometry.parse_wkt("POLYGON ((20 20, 30 20, 30 30, 20 30, 20 20))") }
 

data/spec/{block_11_rtree_order_spec.rb → index_rtree_order_spec.rb}

@@ -2,7 +2,7 @@
 
 require "spec_helper"
 
-RSpec.describe "Release Core Block 11 rtree ordered results" do
+RSpec.describe "Rtree ordered results" do
   let(:entries) do
     [
       [:first, TG::Geometry.parse_wkt("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))")],

data/spec/keyword_validation_spec.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "strict keyword validation" do
+  let(:geom_without_srid) { TG::Geometry.parse_wkt("POINT (1 2)") }
+  let(:wkb) { geom_without_srid.to_wkb }
+
+  it "rejects unsupported SRID and EWKB flags on parse_wkb" do
+    expect { TG::Geometry.parse_wkb(wkb, srid: 4326) }
+      .to raise_error(TG::Geometry::ArgumentError, /unknown keyword: :srid/)
+    expect { TG::Geometry.parse_wkb(wkb, ewkb: true) }
+      .to raise_error(TG::Geometry::ArgumentError, /unknown keyword: :ewkb/)
+  end
+
+  it "rejects public release_gvl knobs on new v0.3.0 APIs" do
+    expect { TG::Geometry.line_string([[0, 0], [1, 1]], release_gvl: true) }
+      .to raise_error(TG::Geometry::ArgumentError, /unknown keyword: :release_gvl/)
+    expect { geom_without_srid.to_ewkb(srid: 4326, release_gvl: true) }
+      .to raise_error(TG::Geometry::ArgumentError, /unknown keyword: :release_gvl/)
+  end
+
+  it "rejects unknown constructor keywords" do
+    square = [[0, 0], [1, 0], [1, 1], [0, 0]]
+
+    expect { TG::Geometry.polygon(square, autoclose: true) }
+      .to raise_error(TG::Geometry::ArgumentError, /unknown keyword: :autoclose/)
+    expect { TG::Geometry.multi_polygon([{ exterior: square, holes: [], extra: true }]) }
+      .to raise_error(TG::Geometry::ArgumentError, /unknown keyword: :extra/)
+  end
+end

data/spec/{block_1_skeleton_spec.rb → load_and_errors_spec.rb}

@@ -2,7 +2,7 @@
 
 require "spec_helper"
 
-RSpec.describe "Release Core Block 1 skeleton" do
+RSpec.describe "Load and error hierarchy" do
   it "compiles the native extension" do
     expect(File.file?(EXT_SO)).to be(true)
   end

data/spec/{expansion_e_low_level_geometry_spec.rb → low_level_geometry_spec.rb}

@@ -2,7 +2,7 @@
 
 require "spec_helper"
 
-RSpec.describe "Expansion Block E low-level geometry wrappers" do
+RSpec.describe "Low-level geometry wrappers" do
   it "exposes Point coordinates without constructing a mutable point wrapper" do
     geom = TG::Geometry.parse_wkt("POINT (1 2)")
 

data/spec/{block_14_memory_gc_hardening_spec.rb → memory_gc_spec.rb}

@@ -3,7 +3,7 @@
 require "spec_helper"
 require "objspace"
 
-RSpec.describe "Release Core Block 14 memory, GC, and compaction hardening" do
+RSpec.describe "Memory, GC, and compaction hardening" do
   let(:small_polygon_wkt) { "POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))" }
   let(:small_polygon_geojson) { '{"type":"Polygon","coordinates":[[[0,0],[10,0],[10,10],[0,10],[0,0]]]}' }
   let(:malformed_geojson) { '{"type":"Polygon","coordinates":[' }

data/spec/nearest_segment_spec.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "nearest_segment" do
+  it "finds nearest line segments and projection points" do
+    line = TG::Geometry.line_string([[0, 0], [10, 0], [10, 10]]).line
+    nearest = line.nearest_segment(5, 3)
+
+    expect(nearest).to be_a(TG::Geometry::NearestSegment)
+    expect(nearest).to be_frozen
+    expect(nearest.segment).to be_a(TG::Geometry::Segment)
+    expect(nearest.index).to be >= 0
+    expect(nearest.distance).to be_within(1e-12).of(3.0)
+    expect(nearest.point).to eq([5.0, 0.0])
+  end
+
+  it "returns zero distance for a point on a segment" do
+    nearest = TG::Geometry.line_string([[0, 0], [10, 0]]).line.nearest_segment(5, 0)
+
+    expect(nearest.index).to eq(0)
+    expect(nearest.distance).to be_within(1e-12).of(0.0)
+    expect(nearest.point).to eq([5.0, 0.0])
+  end
+
+  it "handles outside-bbox and degenerate segments" do
+    outside = TG::Geometry.line_string([[0, 0], [10, 0]]).line.nearest_segment(20, 5)
+    degenerate = TG::Geometry.line_string([[1, 1], [1, 1]]).line.nearest_segment(4, 5)
+
+    expect(outside.index).to eq(0)
+    expect(outside.point).to eq([10.0, 0.0])
+    expect(degenerate.index).to eq(0)
+    expect(degenerate.point).to eq([1.0, 1.0])
+  end
+
+  it "finds nearest ring segments without depending on equal-distance tie break" do
+    ring = TG::Geometry.polygon([[0, 0], [10, 0], [10, 10], [0, 10], [0, 0]]).polygon.exterior_ring
+    center = ring.nearest_segment(5, 5)
+    corner = ring.nearest_segment(0, 0)
+
+    expect(center.index).to be_between(0, 3).inclusive
+    expect(center.distance).to be_within(1e-12).of(5.0)
+    expect(corner.distance).to be_within(1e-12).of(0.0)
+  end
+
+  it "keeps nearest result valid after parent GC" do
+    nearest = TG::Geometry.line_string([[0, 0], [10, 0]]).line.nearest_segment(5, 2)
+
+    GC.start
+    GC.compact if GC.respond_to?(:compact)
+
+    expect(nearest.segment.points).to eq([[0.0, 0.0], [10.0, 0.0]])
+    expect(nearest.point).to eq([5.0, 0.0])
+  end
+
+  it "rejects non-finite coordinates" do
+    line = TG::Geometry.line_string([[0, 0], [10, 0]]).line
+
+    expect { line.nearest_segment(Float::NAN, 0) }.to raise_error(TG::Geometry::ArgumentError)
+    expect { line.nearest_segment(0, Float::INFINITY) }.to raise_error(TG::Geometry::ArgumentError)
+  end
+end

data/spec/postgis_fixtures_spec.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+require "spec_helper"
+
+RSpec.describe "PostGIS EWKB fixtures" do
+  FIXTURE_ROOT = File.expand_path("fixtures/postgis", __dir__)
+
+  CASES = {
+    "point_4326.ewkb" => { srid: 4326, bbox: [37.6, 55.7, 37.6, 55.7] },
+    "polygon_4326_simple.ewkb" => { srid: 4326, bbox: [0.0, 0.0, 10.0, 10.0] },
+    "polygon_4326_with_hole.ewkb" => { srid: 4326, bbox: [0.0, 0.0, 10.0, 10.0] },
+    "polygon_3857.ewkb" => { srid: 3857, bbox: [0.0, 0.0, 10.0, 10.0] },
+    "multipolygon_large.ewkb" => { srid: 4326, bbox: [99.0, 49.0, 101.0, 51.0] }
+  }.freeze
+
+  CASES.each do |filename, expected|
+    it "parses and roundtrips #{filename}" do
+      bytes = File.binread(File.join(FIXTURE_ROOT, filename))
+      geom = TG::Geometry.parse_wkb(bytes)
+      bbox = geom.bbox
+
+      expect(geom.srid).to eq(expected[:srid])
+      expect([bbox.min_x, bbox.min_y, bbox.max_x, bbox.max_y]).to all(be_a(Float))
+      [bbox.min_x, bbox.min_y, bbox.max_x, bbox.max_y].zip(expected[:bbox]).each do |actual, expected_coord|
+        expect(actual).to be_within(1e-9).of(expected_coord)
+      end
+      expect(geom.to_ewkb).to eq(bytes)
+      expect(TG::Geometry.parse_wkb(geom.to_wkb).srid).to be_nil
+    end
+  end
+
+  it "keeps hole coverage semantics stable" do
+    geom = TG::Geometry.parse_wkb(File.binread(File.join(FIXTURE_ROOT, "polygon_4326_with_hole.ewkb")))
+
+    expect(geom.covers_xy?(3, 3)).to be(false)
+    expect(geom.covers_xy?(1, 1)).to be(true)
+  end
+
+  it "checks boundary cases from GeoJSON" do
+    simple = TG::Geometry.parse_wkb(File.binread(File.join(FIXTURE_ROOT, "polygon_4326_simple.ewkb")))
+    data = JSON.parse(File.read(File.join(FIXTURE_ROOT, "boundary_point_cases.geojson")))
+    points = data.fetch("features").to_h do |feature|
+      [feature.fetch("properties").fetch("name"), feature.fetch("geometry").fetch("coordinates")]
+    end
+
+    expect(simple.covers_xy?(*points.fetch("inside_simple"))).to be(true)
+    expect(simple.covers_xy?(*points.fetch("boundary_simple"))).to be(true)
+  end
+
+  it "sanity-checks the large multipolygon quickly" do
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    geom = TG::Geometry.parse_wkb(File.binread(File.join(FIXTURE_ROOT, "multipolygon_large.ewkb")))
+    elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+
+    expect(elapsed).to be < 1.0
+    expect(geom.covers_xy?(100.0, 50.0)).to be(true)
+    expect(geom.covers_xy?(200.0, 50.0)).to be(false)
+  end
+
+  it "documents SRID mismatch as user responsibility" do
+    geom_4326 = TG::Geometry.parse_wkb(File.binread(File.join(FIXTURE_ROOT, "polygon_4326_simple.ewkb")))
+    geom_3857 = TG::Geometry.parse_wkb(File.binread(File.join(FIXTURE_ROOT, "polygon_3857.ewkb")))
+
+    expect(geom_4326.srid).not_to eq(geom_3857.srid)
+    expect(geom_4326.intersects?(geom_3857)).to be(true)
+  end
+end

data/spec/{expansion_i_ractor_spec.rb → ractor_spec.rb}

@@ -2,7 +2,7 @@
 
 require "spec_helper"
 
-RSpec.describe "Expansion Block I Ractor investigation" do
+RSpec.describe "Ractor boundary" do
   it "keeps native wrappers outside Ractor shareability claims" do
     skip "Ractor is not available on this Ruby" unless defined?(Ractor)
 

data/spec/{block_5_rect_api_spec.rb → rect_api_spec.rb}

@@ -2,7 +2,7 @@
 
 require "spec_helper"
 
-RSpec.describe "Release Core Block 5 Rect API" do
+RSpec.describe "Rect API" do
   it "constructs an immutable rect with coordinate accessors" do
     rect = TG::Geometry::Rect.new(1, 2, 5, 8)
 

data/spec/{expansion_b_registry_spec.rb → registry_spec.rb}

@@ -26,7 +26,7 @@ RSpec.describe TG::Geometry::Registry do
     expect(registry.find_covering(25, 25)).to eq(:b)
   end
 
-  it "supports subclass source blocks" do
+  it "supports subclass source definitions" do
     entries = [[:a, zone_a]]
     klass = Class.new(described_class) do
       source { entries }

data/spec/srid_spec.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "SRID metadata" do
+  let(:plain_wkb) { TG::Geometry.parse_wkt("POINT (1 2)").to_wkb }
+  let(:ewkb_4326) { TG::Geometry.parse_wkt("POINT (1 2)").to_ewkb(srid: 4326) }
+  let(:ewkb_3857) { TG::Geometry.parse_wkt("POINT (1 2)").to_ewkb(srid: 3857) }
+  let(:ewkb_0) { TG::Geometry.parse_wkt("POINT (1 2)").to_ewkb(srid: 0) }
+
+  it "returns nil for plain WKB and non-SRID text formats" do
+    expect(TG::Geometry.parse_wkb(plain_wkb).srid).to be_nil
+    expect(TG::Geometry.parse_geojson('{"type":"Point","coordinates":[1,2]}').srid).to be_nil
+    expect(TG::Geometry.parse_wkt("POINT (1 2)").srid).to be_nil
+  end
+
+  it "extracts SRID from little-endian EWKB and hex EWKB" do
+    geom = TG::Geometry.parse_wkb(ewkb_4326)
+
+    expect(geom.srid).to eq(4326)
+    expect([geom.bbox.min_x, geom.bbox.min_y]).to eq([1.0, 2.0])
+    expect(TG::Geometry.parse_wkb(ewkb_3857).srid).to eq(3857)
+    expect(TG::Geometry.parse_wkb(ewkb_0).srid).to eq(0)
+    expect(TG::Geometry.parse_hex(ewkb_4326.unpack1("H*")).srid).to eq(4326)
+  end
+
+  it "extracts SRID from big-endian EWKB" do
+    # Big-endian EWKB: byte order 0, type POINT | SRID flag, SRID 4326, x=1.0, y=2.0.
+    ewkb = [0, 0x20000001, 4326].pack("C N N") + [1.0, 2.0].pack("G G")
+
+    expect(TG::Geometry.parse_wkb(ewkb).srid).to eq(4326)
+    expect(TG::Geometry.parse_wkb(ewkb).point).to eq([1.0, 2.0])
+  end
+
+  it "does not crash on malformed EWKB" do
+    expect { TG::Geometry.parse_wkb("\x01\x01\x00".b) }.to raise_error(TG::Geometry::ParseError)
+  end
+
+  it "uses constructor srid metadata" do
+    expect(TG::Geometry.polygon([[0, 0], [1, 0], [1, 1], [0, 0]], srid: 4326).srid).to eq(4326)
+    expect(TG::Geometry.polygon([[0, 0], [1, 0], [1, 1], [0, 0]]).srid).to be_nil
+  end
+end

data/spec/{expansion_j_full_tg_api_coverage_spec.rb → tg_api_coverage_spec.rb}

@@ -2,7 +2,7 @@
 
 require "spec_helper"
 
-RSpec.describe "Expansion Block J grouped TG API coverage" do
+RSpec.describe "TG API coverage" do
   it "adds safe point and empty geometry constructors without public allocation" do
     point = TG::Geometry.point_zm(1, 2, 3, 4)
 

data/spec/to_ewkb_spec.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Geom#to_ewkb" do
+  let(:geom_without_srid) { TG::Geometry.parse_wkt("POLYGON ((0 0, 10 0, 10 10, 0 10, 0 0))") }
+  let(:geom_with_srid) { TG::Geometry.parse_wkb(geom_without_srid.to_ewkb(srid: 4326)) }
+
+  it "roundtrips semantic geometry and SRID" do
+    ewkb = geom_with_srid.to_ewkb
+    reparsed = TG::Geometry.parse_wkb(ewkb)
+
+    expect(reparsed.srid).to eq(4326)
+    expect(reparsed.type).to eq(:polygon)
+    expect(reparsed.bbox.max_x).to eq(10.0)
+    expect(reparsed.covers_xy?(5, 5)).to be(true)
+  end
+
+  it "can add or override SRID explicitly" do
+    expect(TG::Geometry.parse_wkb(geom_without_srid.to_ewkb(srid: 4326)).srid).to eq(4326)
+    expect(TG::Geometry.parse_wkb(geom_with_srid.to_ewkb(srid: 3857)).srid).to eq(3857)
+  end
+
+  it "returns frozen binary strings" do
+    ewkb = geom_with_srid.to_ewkb
+
+    expect(ewkb.encoding).to eq(Encoding::BINARY)
+    expect(ewkb).to be_frozen
+  end
+
+  it "rejects missing or invalid SRID" do
+    expect { geom_without_srid.to_ewkb }.to raise_error(TG::Geometry::ArgumentError)
+    expect { geom_with_srid.to_ewkb(srid: -1) }.to raise_error(TG::Geometry::ArgumentError)
+    expect { geom_with_srid.to_ewkb(srid: 2**31) }.to raise_error(TG::Geometry::ArgumentError)
+    expect { geom_with_srid.to_ewkb(srid: "4326") }.to raise_error(TG::Geometry::ArgumentError)
+  end
+end

data/spec/{block_2_vendor_spec.rb → vendor_sources_spec.rb}

@@ -4,16 +4,16 @@ require "spec_helper"
 require "open3"
 require "tmpdir"
 
-RSpec.describe "Release Core Block 2 vendored build" do
+RSpec.describe "Vendored source build" do
   let(:vendor_dir) { File.join(ROOT, "ext", "tg_geometry", "vendor") }
 
-  it "keeps tidwall/tg vendored under the contract path" do
+  it "keeps tidwall/tg vendored under the expected path" do
     %w[tg.c tg.h VERSION].each do |name|
       expect(File.file?(File.join(vendor_dir, "tg", name))).to be(true), "missing vendor/tg/#{name}"
     end
   end
 
-  it "keeps rtree.c vendored under the contract path" do
+  it "keeps rtree.c vendored under the expected path" do
     %w[rtree.c rtree.h VERSION].each do |name|
       expect(File.file?(File.join(vendor_dir, "rtree", name))).to be(true), "missing vendor/rtree/#{name}"
     end
@@ -51,7 +51,7 @@ RSpec.describe "Release Core Block 2 vendored build" do
     end
   end
 
-  it "uses the release-core compiler warning flags" do
+  it "uses the expected compiler warning flags" do
     extconf = File.read(File.join(ROOT, "ext", "tg_geometry", "extconf.rb"))
 
     expect(extconf).to include('"-std=c11"')