docs(agents): tooling + architecture-upkeep rules, with tool tests (#24)

Merged PR #24: tooling + architecture-upkeep rules, tool tests

Co-authored-by: Zwitschi <zwitschi82@gmail.com>

Geo/tools/block_height_report.py

@@ -22,6 +22,24 @@ import osm_common as oc
 LEVEL_HEIGHT = 3.2
 
 
+def classify_height(tags, level_height=LEVEL_HEIGHT):
+    """Return (height_m, source) for one OSM way's tags.
+
+    Extracted from `main()` so the classification is testable: the roof/shelter
+    rule and the "height tag beats levels beats guess" order are the parts that
+    actually decide what the blockout should render.
+    """
+    if tags.get("building") == "roof" or tags.get("amenity") == "shelter":
+        kind = "roof" if tags.get("building") == "roof" else "shelter"
+        return 0.0, f"not a building volume ({kind})"
+    if tags.get("height"):
+        return float(tags["height"]), "height tag"
+    if tags.get("building:levels"):
+        return (float(tags["building:levels"]) * level_height,
+                f"levels x {level_height} m")
+    return 2 * level_height, f"GUESS: default 2 levels x {level_height} m"
+
+
 def main():
     ap = argparse.ArgumentParser()
     ap.add_argument("osm")
@@ -43,21 +61,7 @@ def main():
         pts = oc.way_points(nodes, refs)
         if not pts or not in_block(pts):
             continue
-        tag_height = tags.get("height")
-        levels = tags.get("building:levels")
-        # Non-building volumes must not be extruded as two-storey blocks: a
-        # `building=roof` is an elevated slab and a public-transport shelter is a
-        # small street structure. Treating them as "2 levels x 3.2 m" produced a
-        # 6.4 m block for a bus shelter and a canopy.
-        if tags.get("building") == "roof" or tags.get("amenity") == "shelter":
-            kind = "roof" if tags.get("building") == "roof" else "shelter"
-            height, source = 0.0, f"not a building volume ({kind})"
-        elif tag_height:
-            height, source = float(tag_height), "height tag"
-        elif levels:
-            height, source = float(levels) * LEVEL_HEIGHT, f"levels x {LEVEL_HEIGHT} m"
-        else:
-            height, source = 2 * LEVEL_HEIGHT, f"GUESS: default 2 levels x {LEVEL_HEIGHT} m"
+        height, source = classify_height(tags)
         nearest = min(oc.project(p, line, lat0, lon0, lengths)[0] for p in pts)
         side = "S" if oc.project(pts[0], line, lat0, lon0, lengths)[2] < 0 else "N"
         rows.append((side, nearest, wid, tags.get("name", "") or tags.get("addr:housenumber", ""),