openmapstack 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

openmapstack/__init__.py

@@ -3,4 +3,4 @@
 from .validation import Check, ValidationResult, validate_project
 
 __all__ = ["Check", "ValidationResult", "validate_project"]
-__version__ = "0.3.0"
+__version__ = "0.4.0"

openmapstack/api.py

@@ -263,6 +263,8 @@ def api_info() -> dict[str, Any]:
         "package_version": __version__,
         "check_api_version": CHECK_API_VERSION,
         "project_schema": PROJECT_SCHEMA,
+        "skill_snapshot_schemas": ["openmapstack-skill-snapshot/v1", "openmapstack-skill-snapshot/v2"],
+        "benchmark_arm_schemas": ["openmapstack-benchmark-arm/v1", "openmapstack-benchmark-arm/v2"],
         "result_schemas": {
             "check": CHECK_RESULT_SCHEMA,
             "verify": VERIFY_RESULT_SCHEMA,

openmapstack/checks/geodata.py

@@ -48,9 +48,9 @@ def _geometry_column(con, rel: str, preferred: str | None = None) -> str | None:
     except Exception:  # noqa: BLE001
         return preferred
     by_name = {str(name): str(type_name).upper() for name, type_name, *_ in columns}
-    if preferred and preferred in by_name:
-        return preferred
-    typed = [name for name, type_name in by_name.items() if type_name == "GEOMETRY"]
+    if preferred:
+        return preferred if preferred in by_name else None
+    typed = [name for name, type_name in by_name.items() if type_name == "GEOMETRY" or type_name.startswith("GEOMETRY(")]
     if len(typed) == 1:
         return typed[0]
     candidates = typed or list(by_name)
@@ -60,6 +60,37 @@ def _geometry_column(con, rel: str, preferred: str | None = None) -> str | None:
     return typed[0] if typed else preferred
 
 
+def _geometry_expression(con, rel: str, preferred: str | None = None) -> str | None:
+    """Resolve typed geometry or WKB without assigning an invented CRS.
+
+    Spatial reads GeoParquet metadata into GEOMETRY (including CRS-qualified
+    types). Bare WKB Parquet remains BLOB: it can be checked for validity, but
+    ST_CRS on its decoded value correctly reports missing metadata.
+    """
+    column = _geometry_column(con, rel, preferred)
+    if column is None:
+        return None
+    columns = con.execute(f"SELECT * FROM {rel} LIMIT 0").description or []
+    types = {str(name): str(kind).upper() for name, kind, *_ in columns}
+    identifier = '"' + column.replace('"', '""') + '"'
+    if types.get(column) == "BLOB":
+        return f"ST_GeomFromWKB({identifier})"
+    if types.get(column, "").startswith("GEOMETRY"):
+        return identifier
+    return None
+
+
+def _invalid_geometry_count(con, rel: str, preferred: str | None = None) -> int | None:
+    expression = _geometry_expression(con, rel, preferred)
+    if expression is None:
+        return None
+    # Missing geometries cannot silently count as valid via SQL NULL semantics.
+    return con.execute(
+        f"SELECT COUNT(*) FROM {rel} "
+        f"WHERE {expression} IS NULL OR NOT ST_IsValid({expression})"
+    ).fetchone()[0]
+
+
 def row_count(workspace: Path, path: str, equals: int | None = None, at_least: int | None = None,
               at_most: int | None = None, project_dir: str = ".") -> AssertionResult:
     target = project_root(workspace, project_dir) / path
@@ -92,12 +123,10 @@ def geometry_all_valid(workspace: Path, path: str, project_dir: str = ".") -> As
         return not_testable("duckdb spatial not available in this environment", code="duckdb_unavailable")
     try:
         rel = _read(con, target)
-        column = _geometry_column(con, rel)
-        if column is None:
-            return not_testable(f"{path} has no geometry column", code="geometry_column_missing")
-        total, invalid = con.execute(
-            f'SELECT COUNT(*), SUM(CASE WHEN NOT ST_IsValid("{column}") THEN 1 ELSE 0 END) FROM {rel}'
-        ).fetchone()
+        invalid = _invalid_geometry_count(con, rel)
+        if invalid is None:
+            return failed(f"{path} has no geometry column", code="geometry_column_missing")
+        total = con.execute(f"SELECT COUNT(*) FROM {rel}").fetchone()[0]
     except Exception as exc:  # noqa: BLE001
         return not_testable(f"could not validate geometry in {path}: {exc}", code="read_error")
     invalid = invalid or 0
@@ -299,10 +328,14 @@ def dataset_crs_is(
         return not_testable("duckdb spatial not available in this environment", code="duckdb_unavailable")
     try:
         rel = _read(con, target)
-        column = _geometry_column(con, rel, geometry_field)
-        if column is None:
-            return not_testable(f"{path} has no geometry column", code="geometry_column_missing")
-        rows = con.execute(f'SELECT DISTINCT ST_CRS("{column}") FROM {rel}').fetchall()
+        expression = _geometry_expression(con, rel, geometry_field)
+        if expression is None:
+            return failed(f"{path} has no geometry column", code="geometry_column_missing")
+        # The NULL row preserves a typed column's CRS even for an empty dataset.
+        rows = con.execute(
+            f"SELECT DISTINCT ST_CRS(geometry_value) FROM "
+            f"(SELECT {expression} AS geometry_value FROM {rel} UNION ALL SELECT NULL)"
+        ).fetchall()
     except Exception as exc:  # noqa: BLE001
         return not_testable(f"could not inspect CRS metadata in {path}: {exc}", code="read_error")
     actual = sorted({str(row[0]).upper() for row in rows if row and row[0]})
@@ -316,3 +349,36 @@ def dataset_crs_is(
             expected=expected.upper(),
         )
     return passed(f"{path} actual CRS metadata is {expected.upper()}", actual=actual)
+
+
+# GeoParquet always stores longitude/latitude and defaults WGS 84 to
+# OGC:CRS84, so a declared EPSG:4326 is written as either identifier.
+_EQUIVALENT_CRS = ({"EPSG:4326", "OGC:CRS84"},)
+
+
+def dataset_crs_matches_storage_crs(
+    workspace: Path,
+    path: str,
+    geometry_field: str | None = None,
+    project_dir: str = ".",
+) -> AssertionResult:
+    """Require a dataset's real CRS metadata to match `processing.storage_crs`.
+
+    Checks that the project writes what it declares, without prescribing
+    which storage CRS it should choose.
+    """
+    from . import get_in, load_project_yaml
+
+    proj = load_project_yaml(workspace, project_dir)
+    if proj is None:
+        return failed("project.yaml missing", code="manifest_missing")
+    declared = get_in(proj, "processing.storage_crs")
+    if not isinstance(declared, str) or not declared.strip():
+        return failed("processing.storage_crs is not declared", code="storage_crs_missing")
+    declared = declared.strip().upper()
+    for group in _EQUIVALENT_CRS:
+        if declared in group:
+            results = [dataset_crs_is(workspace, path, crs, geometry_field, project_dir) for crs in sorted(group)]
+            match = next((result for result in results if result.status == "passed"), None)
+            return match or results[0]
+    return dataset_crs_is(workspace, path, declared, geometry_field, project_dir)

openmapstack/checks/qgis.py

@@ -9,13 +9,15 @@ validation isn't available.
 from __future__ import annotations
 
 import html
+import json
 import re
+import sqlite3
 import tempfile
 import zipfile
 from pathlib import Path
 from typing import Any
 
-from . import AssertionResult, failed, get_in, load_project_yaml, not_testable, passed, project_root
+from . import AssertionResult, failed, get_in, load_project_yaml, not_testable, passed, project_root, warning
 
 
 def _extract_qgs_xml(qgz_path: Path) -> str | None:
@@ -31,9 +33,13 @@ def _extract_qgs_xml(qgz_path: Path) -> str | None:
 
 
 def static_valid(workspace: Path, path: str = "project.qgz", project_dir: str = ".") -> AssertionResult:
-    """The .qgz opens as a zip containing a .qgs, every <datasource> referencing
-    a relative file path resolves on disk, and GeoPackage datasources declare
-    a layername= (otherwise GDAL silently loads a non-spatial attribute table)."""
+    """The .qgz opens as a zip containing a .qgs, every local <datasource> is a
+    relative path that resolves on disk, and GeoPackage datasources declare
+    a layername= (otherwise GDAL silently loads a non-spatial attribute table).
+
+    An absolute path fails even when it exists: a QGIS-authored project once
+    shipped the author's own paths and passed because they resolved locally.
+    """
     qgz_path = project_root(workspace, project_dir) / path
     if not qgz_path.exists():
         return failed(f"{path} does not exist", code="file_missing")
@@ -57,6 +63,10 @@ def static_valid(workspace: Path, path: str = "project.qgz", project_dir: str =
         if ds.startswith(("http", "type=xyz", "contextualWMSLegend", "crs=")) or "url=" in ds:
             continue
         raw_path = ds.split("|", 1)[0]
+        if Path(raw_path).is_absolute() or re.match(r"^[A-Za-z]:[\\/]", raw_path):
+            # Resolves on the machine that wrote it and nowhere else.
+            errors.append(f"datasource uses an absolute path: {raw_path}")
+            continue
         if raw_path.lower().endswith(".gpkg") and "layername=" not in ds:
             errors.append(f"GeoPackage datasource missing layername=: {ds}")
         resolved = (root / raw_path).resolve() if raw_path.startswith("./") or not raw_path.startswith("/") else Path(raw_path)
@@ -68,6 +78,143 @@ def static_valid(workspace: Path, path: str = "project.qgz", project_dir: str =
     return passed(f"{path} static-valid: {len(datasources)} datasource(s), all files resolve")
 
 
+#: File formats whose GDAL drivers are built into every QGIS build. Anything
+#: else may need an optional driver: Debian/Ubuntu QGIS packages ship without
+#: Parquet and Arrow (checked on QGIS 3.40.15, GDAL 3.12.2), and formats such
+#: as Personal Geodatabase depend on extra libraries.
+PORTABLE_SUFFIXES = frozenset({".gpkg", ".geojson", ".json", ".fgb", ".shp", ".tif", ".tiff"})
+OPTIONAL_DRIVERS = {".parquet": "Parquet", ".geoparquet": "Parquet", ".arrow": "Arrow", ".feather": "Arrow", ".arrows": "Arrow"}
+
+
+def _is_provider_datasource(datasource: str) -> bool:
+    """Remote services and provider connection strings are not local files."""
+    location = datasource.split("|", 1)[0]
+    return datasource.startswith(("http", "type=xyz", "contextualWMSLegend", "crs=")) or "=" in location
+
+
+def datasources_portable(workspace: Path, path: str = "project.qgz", project_dir: str = ".") -> AssertionResult:
+    """Every local file datasource uses a format every QGIS build reads.
+
+    Portable formats are an allowlist: GeoPackage, GeoJSON, FlatGeobuf,
+    Shapefile and GeoTIFF. A live trial pointed QGIS at GeoParquet; a stock
+    Ubuntu QGIS opened the layer invalid and drew nothing while every static
+    check passed. Remote and provider datasources are out of scope. A warning,
+    not a failure: builds with the extra driver do open other formats.
+    """
+    xml, _qgz_path, error = _qgs_xml(workspace, path, project_dir)
+    if error == "file_missing":
+        return failed(f"{path} does not exist", code="file_missing")
+    if error == "not_a_zip":
+        return failed(f"{path} is not a valid zip archive", code="not_a_zip")
+    if xml is None:
+        return failed(f"{path} does not contain a .qgs document", code="no_qgs_document")
+    unportable: dict[str, str] = {}
+    for datasource in re.findall(r"<datasource>(.*?)</datasource>", xml, re.DOTALL):
+        datasource = datasource.strip()
+        if not datasource or _is_provider_datasource(datasource):
+            continue
+        suffix = Path(datasource.split("|", 1)[0]).suffix.lower()
+        if suffix not in PORTABLE_SUFFIXES:
+            unportable[datasource] = OPTIONAL_DRIVERS.get(suffix, f"{suffix or 'no extension'} is outside the portable set")
+    if unportable:
+        return warning(
+            "layers use formats many QGIS builds cannot open, so they load invalid there: "
+            + ", ".join(f"{source} ({reason})" for source, reason in unportable.items())
+            + "; point QGIS at a GeoPackage, GeoJSON or FlatGeobuf copy",
+            code="datasource_format_not_portable",
+            datasources=unportable,
+        )
+    return passed(f"{path}: every local file datasource uses a format every QGIS build reads")
+
+
+def _data_crs(root: Path, datasource: str) -> str | None:
+    """The CRS a GeoJSON or GeoPackage layer's data is actually in, or ``None``.
+
+    GeoJSON without a ``crs`` member is WGS84 by RFC 7946, which is how GDAL
+    reads it. GeoPackage records the SRS per geometry table.
+    """
+    location, *options = datasource.split("|")
+    path = root / location
+    if not path.is_file():
+        return None
+    suffix = path.suffix.lower()
+    if suffix in {".geojson", ".json"}:
+        try:
+            crs = json.loads(path.read_text(encoding="utf-8")).get("crs")
+        except (OSError, ValueError, AttributeError):
+            return None
+        if not crs:
+            return "EPSG:4326"
+        name = str((crs.get("properties") or {}).get("name", "")) if isinstance(crs, dict) else ""
+        if "CRS84" in name.upper():
+            return "EPSG:4326"
+        match = re.search(r"EPSG:+(\d+)", name, re.IGNORECASE)
+        return f"EPSG:{match.group(1)}" if match else None
+    if suffix == ".gpkg":
+        layer = next((option.split("=", 1)[1] for option in options if option.startswith("layername=")), None)
+        try:
+            connection = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+            try:
+                rows = connection.execute(
+                    "SELECT g.table_name, s.organization, s.organization_coordsys_id FROM gpkg_geometry_columns g"
+                    " JOIN gpkg_spatial_ref_sys s ON g.srs_id = s.srs_id"
+                ).fetchall()
+            finally:
+                connection.close()
+        except sqlite3.Error:
+            return None
+        matches = [row for row in rows if layer is None or row[0] == layer]
+        if len(matches) != 1 or str(matches[0][1]).upper() != "EPSG":
+            return None
+        return f"EPSG:{matches[0][2]}"
+    return None
+
+
+def layer_crs_matches_data(workspace: Path, path: str = "project.qgz", project_dir: str = ".") -> AssertionResult:
+    """Each GeoJSON or GeoPackage layer's declared CRS is the CRS of its data.
+
+    QGIS trusts a hand-written ``<srs>``. A live trial declared EPSG:3301 on
+    WGS84 GeoJSON, so QGIS placed the roads a few metres from the grid's
+    origin and the map drew nothing where the analysis was, while every
+    static check passed. Layers whose data CRS cannot be read here are
+    skipped; missing files are reported by ``qgis.static_valid``.
+    """
+    xml, _qgz_path, error = _qgs_xml(workspace, path, project_dir)
+    if error == "file_missing":
+        return failed(f"{path} does not exist", code="file_missing")
+    if error == "not_a_zip":
+        return failed(f"{path} is not a valid zip archive", code="not_a_zip")
+    if xml is None:
+        return failed(f"{path} does not contain a .qgs document", code="no_qgs_document")
+    root = project_root(workspace, project_dir)
+    compared: dict[str, dict[str, str]] = {}
+    mismatched: list[str] = []
+    for layer_xml in re.findall(r"<maplayer[ >].*?</maplayer>", xml, re.DOTALL):
+        datasource = html.unescape((re.search(r"<datasource>(.*?)</datasource>", layer_xml, re.DOTALL) or [None, ""])[1]).strip()
+        authid = re.search(r"<authid>(.*?)</authid>", layer_xml, re.DOTALL)
+        if not datasource or authid is None or _is_provider_datasource(datasource):
+            continue
+        actual = _data_crs(root, datasource)
+        if actual is None:
+            continue
+        name_match = re.search(r"<layername>(.*?)</layername>", layer_xml, re.DOTALL)
+        name = name_match.group(1).strip() if name_match else datasource
+        declared = authid.group(1).strip()
+        compared[name] = {"declared": declared, "data": actual}
+        if declared.upper() != actual.upper():
+            mismatched.append(name)
+    if mismatched:
+        return failed(
+            "layers declare a CRS their data is not in, so QGIS draws them in the wrong place: "
+            + ", ".join(f"{name} (declared {compared[name]['declared']}, data {compared[name]['data']})" for name in mismatched),
+            code="layer_crs_mismatch",
+            layers={name: compared[name] for name in mismatched},
+        )
+    if not compared:
+        return not_testable("no local GeoJSON or GeoPackage layer to compare", code="no_comparable_layers")
+    return passed(f"all {len(compared)} comparable layers declare the CRS their data is in", layers=compared)
+
+
 _QGIS_APPLICATION: Any = None
 
 

openmapstack/checks/rerun.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import hashlib
 import json
 import shlex
+import sqlite3
 from pathlib import Path
 from typing import Any
 
@@ -171,12 +172,68 @@ def _parquet_snapshot(path: Path, ignored_fields: set[str]) -> dict[str, Any]:
     return {"schema": schema, "rows": sorted(normalized_rows, key=_stable_json)}
 
 
+def _geopackage_snapshot(path: Path, ignored_fields: set[str]) -> Any:
+    """Schema, core metadata and rows of a GeoPackage, without its write time.
+
+    ``gpkg_contents.last_change`` records when the file was written, so a
+    byte hash reports every rebuild as changed even when no feature differs.
+    Everything a consumer interprets is kept: column definitions, geometry
+    columns and the SRS definitions they reference. Geometry blobs are
+    compared as stored: one writer encodes one geometry identically.
+    """
+    connection = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+
+    def metadata(query: str) -> list[list[Any]]:
+        try:
+            return [list(row) for row in connection.execute(query).fetchall()]
+        except sqlite3.OperationalError:  # optional table absent
+            return []
+
+    try:
+        contents = connection.execute(
+            "SELECT table_name, data_type, srs_id, min_x, min_y, max_x, max_y FROM gpkg_contents ORDER BY table_name"
+        ).fetchall()
+        geometry_columns = metadata("SELECT * FROM gpkg_geometry_columns ORDER BY table_name")
+        spatial_reference_systems = metadata(
+            "SELECT srs_name, srs_id, organization, organization_coordsys_id, definition"
+            " FROM gpkg_spatial_ref_sys ORDER BY srs_id"
+        )
+        schemas = {}
+        tables = {}
+        for table_name, *_ in contents:
+            schemas[table_name] = [
+                list(column[1:]) for column in connection.execute(f"PRAGMA table_info({_sql_identifier(table_name)})")
+            ]
+            cursor = connection.execute(f"SELECT * FROM {_sql_identifier(table_name)}")
+            names = [column[0] for column in cursor.description]
+            rows = [
+                {
+                    name: value.hex() if isinstance(value, bytes) else _normalize_json(value, ignored_fields)
+                    for name, value in zip(names, row, strict=True)
+                    if name not in ignored_fields
+                }
+                for row in cursor.fetchall()
+            ]
+            tables[table_name] = sorted(rows, key=_stable_json)
+    finally:
+        connection.close()
+    return {
+        "contents": [list(row) for row in contents],
+        "geometry_columns": geometry_columns,
+        "spatial_reference_systems": spatial_reference_systems,
+        "schemas": schemas,
+        "tables": tables,
+    }
+
+
 def _semantic_snapshot(path: Path, ignored_fields: set[str]) -> Any:
     suffix = path.suffix.lower()
     if suffix in {".json", ".geojson"}:
         return _normalize_json(json.loads(path.read_text(encoding="utf-8")), ignored_fields)
     if suffix in {".parquet", ".geoparquet"}:
         return _parquet_snapshot(path, ignored_fields)
+    if suffix == ".gpkg":
+        return _geopackage_snapshot(path, ignored_fields)
     return {"sha256": hashlib.sha256(path.read_bytes()).hexdigest()}
 
 

openmapstack/checks/validation.py

@@ -176,6 +176,51 @@ def run_record_matches(
     return passed(f"report run_id {run_id!r} matches a real run record with consistent hashes")
 
 
+def sample_run_not_promoted(
+    workspace: Path, project_dir: str = ".", runs_dir: str = "runs"
+) -> AssertionResult:
+    """A sampled run is never the canonical run of record.
+
+    Sampling clips or thins the inputs, so its outputs are evidence that the
+    pipeline executes, never evidence of the answer. `runs.latest` is what
+    `verify`, the clean-rerun protocol, and every expectation attestation bind
+    to, so a sampled record reaching it would launder a smoke test into a
+    result. A sampled record must also state what it *realized*, not only what
+    was requested.
+    """
+    from openmapstack.sampling import run_mode, run_record_errors
+
+    proj = load_project_yaml(workspace, project_dir)
+    if proj is None:
+        return failed("project.yaml missing", code="manifest_missing")
+    root = project_root(workspace, project_dir)
+    directory = root / runs_dir
+    if not directory.is_dir():
+        return not_testable(f"no {runs_dir}/ directory", code="runs_dir_missing")
+
+    latest_id = str(get_in(proj, "runs.latest.id", "") or "")
+    sampled: list[str] = []
+    problems: list[str] = []
+    for record_path in sorted(directory.glob("*.json")):
+        record = load_json(record_path)
+        if not isinstance(record, dict):
+            continue
+        problems.extend(f"{record_path.name}: {problem}" for problem in run_record_errors(record))
+        if run_mode(record) == "sampled":
+            sampled.append(record_path.stem)
+
+    if latest_id and latest_id in sampled:
+        return failed(
+            f"runs.latest is sampled run {latest_id!r}; a sampled run cannot be the canonical run",
+            code="sampled_run_promoted",
+        )
+    if problems:
+        return failed(f"invalid run mode/sample declaration: {problems}", code="sample_record_invalid")
+    if not sampled:
+        return passed("no sampled run records; runs.latest is canonical")
+    return passed(f"{len(sampled)} sampled run record(s) present and none is runs.latest")
+
+
 def no_prose_only_validation(
     workspace: Path, check_id: str, project_dir: str = ".", report_path: str = "validation/latest-report.json"
 ) -> AssertionResult:
@@ -208,7 +253,7 @@ def report_evidence_recomputes(
     and optional id field. This avoids accepting internally consistent prose
     or invented counters as proof that a GIS check actually ran.
     """
-    from .geodata import _connect, _read
+    from .geodata import _connect, _invalid_geometry_count, _read
 
     report = load_json(project_root(workspace, project_dir) / report_path)
     if report is None:
@@ -246,9 +291,11 @@ def report_evidence_recomputes(
             if metric == "row_count":
                 actual = con.execute(f"SELECT COUNT(*) FROM {relation}").fetchone()[0]
             elif metric == "invalid_geometry_count":
-                actual = con.execute(
-                    f"SELECT COUNT(*) FROM {relation} WHERE NOT ST_IsValid(geom)"
-                ).fetchone()[0]
+                actual = _invalid_geometry_count(con, relation, declaration.get("geometry_field"))
+                if actual is None:
+                    return failed(
+                        f"{relative} has no matching geometry column", code="geometry_column_missing"
+                    )
             elif metric in {"duplicate_count", "null_count"}:
                 field = declaration.get("field")
                 if not isinstance(field, str) or not field: