iwxxm-validate 0.1.0__py3-none-any.whl

iwxxm_validate/__init__.py

@@ -0,0 +1,21 @@
+"""IWXXM XSD + Schematron validation engine (F2 package)."""
+
+from __future__ import annotations
+
+from iwxxm_validate.api import validate
+from iwxxm_validate.models import Issue, ValidationReport
+from iwxxm_validate.native import clear_schema_caches, rust_available, rust_module
+from iwxxm_validate.validate_iwxxm import validate_iwxxm
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Issue",
+    "ValidationReport",
+    "__version__",
+    "clear_schema_caches",
+    "rust_available",
+    "rust_module",
+    "validate",
+    "validate_iwxxm",
+]

iwxxm_validate/api.py

@@ -0,0 +1,119 @@
+"""Public ``validate()`` entrypoint for IWXXM XSD + Schematron (F2)."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from iwxxm_validate.models import Issue, ValidationReport
+from iwxxm_validate.paths import us_catalog_path
+from iwxxm_validate.schematron import validate_schematron
+from iwxxm_validate.xsd import validate_xsd
+
+_DEFAULT_LEVELS: tuple[str, ...] = ("xsd", "schematron")
+_VALID_PROFILES = frozenset({"annex3", "iwxxm_us"})
+_VALID_LEVELS = frozenset({"xsd", "schematron"})
+
+
+def validate(
+    xml_content: str,
+    *,
+    iwxxm_version: str,
+    profile: str = "annex3",
+    levels: Sequence[str] | None = None,
+) -> ValidationReport:
+    """
+    Validate IWXXM XML against vendored XSD and/or Schematron.
+
+    Parameters
+    ----------
+    xml_content :
+        IWXXM XML document.
+    iwxxm_version :
+        Release line (e.g. ``2023-1``).
+    profile :
+        ``annex3`` (default) or ``iwxxm_us`` (requires vendored US catalog).
+    levels :
+        Subset of ``xsd`` / ``schematron``. Default runs both.
+
+    Returns
+    -------
+    ValidationReport
+        ``ok`` is ``False`` when any error-severity issue is present.
+        XSLT2 Schematron yields non-blocking ``SCHEMATRON_SKIPPED`` (D-S008-T21-sch).
+    """
+    if profile not in _VALID_PROFILES:
+        return ValidationReport(
+            ok=False,
+            iwxxm_version=iwxxm_version,
+            profile=profile,
+            issues=[
+                Issue(
+                    severity="error",
+                    code="INVALID_PROFILE",
+                    message=f"Unknown profile {profile!r}; expected annex3|iwxxm_us",
+                    layer="xsd",
+                )
+            ],
+        )
+
+    selected = tuple(levels) if levels is not None else _DEFAULT_LEVELS
+    unknown = [level for level in selected if level not in _VALID_LEVELS]
+    if unknown:
+        return ValidationReport(
+            ok=False,
+            iwxxm_version=iwxxm_version,
+            profile=profile,
+            issues=[
+                Issue(
+                    severity="error",
+                    code="INVALID_LEVELS",
+                    message=f"Unknown validation levels: {unknown}",
+                    layer="xsd",
+                )
+            ],
+        )
+
+    issues: list[Issue] = []
+
+    if profile == "iwxxm_us" and us_catalog_path() is None:
+        issues.append(
+            Issue(
+                severity="error",
+                code="US_CATALOG_NOT_FOUND",
+                message="profile=iwxxm_us but vendor iwxxm-us catalog is missing",
+                layer="xsd",
+            )
+        )
+        return ValidationReport(
+            ok=False,
+            iwxxm_version=iwxxm_version,
+            profile=profile,
+            issues=issues,
+        )
+
+    if "xsd" in selected:
+        issues.extend(validate_xsd(xml_content, iwxxm_version))
+        # Malformed XML already reported — skip Schematron
+        if any(issue.code == "XML_SYNTAX_ERROR" for issue in issues):
+            return ValidationReport(
+                ok=False,
+                iwxxm_version=iwxxm_version,
+                profile=profile,
+                issues=issues,
+            )
+
+    if "schematron" in selected:
+        # Skip Schematron when XSD already failed hard on syntax
+        if not any(issue.code == "XML_SYNTAX_ERROR" for issue in issues):
+            issues.extend(validate_schematron(xml_content, iwxxm_version))
+
+    ok = not any(issue.severity == "error" for issue in issues)
+    return ValidationReport(
+        ok=ok,
+        iwxxm_version=iwxxm_version,
+        profile=profile,
+        issues=issues,
+    )
+
+
+__all__ = ["validate"]

iwxxm_validate/cli.py

@@ -0,0 +1,86 @@
+"""Optional thin CLI for ``iwxxm-validate`` (E10-39 / T3.9)."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from iwxxm_validate.codec import json_encoder
+from iwxxm_validate.validate_iwxxm import validate_iwxxm
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="iwxxm-validate",
+        description="Validate IWXXM XML (XSD + Schematron via validate_iwxxm SDK).",
+    )
+    parser.add_argument(
+        "path",
+        type=Path,
+        help="Path to an IWXXM XML file",
+    )
+    parser.add_argument(
+        "--version",
+        dest="iwxxm_version",
+        default="2023-1",
+        help="IWXXM release line (default: 2023-1)",
+    )
+    parser.add_argument(
+        "--profile",
+        default="annex3",
+        choices=("annex3", "iwxxm_us"),
+        help="Schema profile (default: annex3)",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit ValidationReport as JSON on stdout",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """
+    Run ``iwxxm-validate`` CLI.
+
+    Parameters
+    ----------
+    argv :
+        Argument vector (defaults to ``sys.argv[1:]``).
+
+    Returns
+    -------
+    int
+        ``0`` when ``report.ok``; ``1`` on validation errors or I/O failure.
+    """
+    parser = _build_parser()
+    args = parser.parse_args(list(argv) if argv is not None else None)
+    path: Path = args.path
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        print(f"error: cannot read {path}: {exc}", file=sys.stderr)
+        return 1
+
+    report = validate_iwxxm(
+        text,
+        iwxxm_version=args.iwxxm_version,
+        profile=args.profile,
+    )
+    if args.json:
+        sys.stdout.write(json_encoder.encode(report).decode("utf-8"))
+        sys.stdout.write("\n")
+    else:
+        status = "ok" if report.ok else "fail"
+        print(f"{status} version={report.iwxxm_version} profile={report.profile} issues={len(report.issues)}")
+        for issue in report.issues:
+            loc = f" @{issue.location}" if issue.location else ""
+            print(f"  {issue.severity}:{issue.code}{loc} {issue.message}")
+
+    return 0 if report.ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

iwxxm_validate/codec.py

@@ -0,0 +1,12 @@
+"""Reusable msgspec JSON codec instances (ADR-016)."""
+
+from __future__ import annotations
+
+import msgspec
+
+from iwxxm_validate.models import ValidationReport
+
+json_encoder = msgspec.json.Encoder()
+json_decoder = msgspec.json.Decoder(ValidationReport)
+
+__all__ = ["json_decoder", "json_encoder"]

iwxxm_validate/models.py

@@ -0,0 +1,61 @@
+"""msgspec models for IWXXM validation reports (ADR-016)."""
+
+from __future__ import annotations
+
+import msgspec
+
+
+class Issue(msgspec.Struct, frozen=True):
+    """
+    Single validation finding.
+
+    Parameters
+    ----------
+    severity :
+        ``error``, ``warning``, or ``info``.
+    code :
+        Machine-readable issue code (e.g. ``XML_SYNTAX_ERROR``).
+    message :
+        Human-readable description.
+    layer :
+        Validation layer (``xsd``, ``schematron``, ``wellformed``).
+    location :
+        Optional document location hint.
+    start :
+        Optional inclusive character / document offset when known.
+    end :
+        Optional exclusive character / document offset when known.
+    """
+
+    severity: str
+    code: str
+    message: str
+    layer: str
+    location: str | None = None
+    start: int | None = None
+    end: int | None = None
+
+
+class ValidationReport(msgspec.Struct, frozen=True):
+    """
+    Aggregate result of ``validate()``.
+
+    Parameters
+    ----------
+    ok :
+        ``True`` when no blocking (error-severity) issues remain.
+    iwxxm_version :
+        Requested IWXXM release line.
+    profile :
+        ``annex3`` or ``iwxxm_us``.
+    issues :
+        Ordered list of findings (may include non-blocking warnings).
+    """
+
+    ok: bool
+    iwxxm_version: str
+    profile: str
+    issues: list[Issue]
+
+
+__all__ = ["Issue", "ValidationReport"]

iwxxm_validate/native.py

@@ -0,0 +1,44 @@
+"""Optional PyO3 extension loader (F13 / E10-36; mirrors tac2iwxxm ADR-017).
+
+The ``iwxxm_validate._rust`` module is built by maturin. Pure-Python lxml paths keep
+working when the extension is absent (local without rustc); CI rust job requires it.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def rust_available() -> bool:
+    """Return True when the compiled ``iwxxm_validate._rust`` extension imports."""
+    try:
+        from iwxxm_validate import _rust  # type: ignore[attr-defined]
+    except ImportError:
+        return False
+    return _rust is not None  # pragma: no cover
+
+
+def clear_schema_caches() -> None:
+    """Clear process-wide compiled XSD/Schematron caches (native only; no-op if absent)."""
+    mod = rust_module()
+    if mod is None:
+        return
+    clearer = getattr(mod, "clear_schema_caches", None)
+    if callable(clearer):
+        clearer()
+
+
+def rust_module() -> Any | None:
+    """
+    Return the loaded ``_rust`` module, or ``None`` if unavailable.
+
+    Returns
+    -------
+    Any | None
+        Extension module or ``None``.
+    """
+    try:
+        from iwxxm_validate import _rust  # type: ignore[attr-defined]
+    except ImportError:
+        return None
+    return _rust  # type: ignore[no-any-return]  # pragma: no cover

iwxxm_validate/paths.py

@@ -0,0 +1,145 @@
+"""Resolve IWXXM / IWXXM-US schema paths (packaged subset or monorepo vendor).
+
+Resolution order (E10-34 / E10-6):
+
+1. ``IWXXM_VALIDATE_REPO_ROOT`` / ``IWXXM_SCHEMAS_ROOT`` environment overrides
+2. Packaged runtime subset under ``iwxxm_validate/schemas/`` (wheel / after sync)
+3. Monorepo ``vendor/schemas/*`` when developing inside this repository
+"""
+
+from __future__ import annotations
+
+import os
+from functools import lru_cache
+from pathlib import Path
+
+_PACKAGE_DIR = Path(__file__).resolve().parent
+_PACKAGE_SCHEMAS = _PACKAGE_DIR / "schemas"
+_PACKAGE_ROOT = _PACKAGE_DIR.parents[1]
+_DEFAULT_REPO_ROOT = _PACKAGE_ROOT.parents[1]
+
+
+def packaged_schemas_root() -> Path | None:
+    """
+    Return the packaged schema subset root when materialised.
+
+    The subset is present after ``make sync-iwxxm-validate-schemas`` or inside a
+    published wheel. ``MANIFEST.json`` alone does not count as materialised.
+    """
+    iwxxm = _PACKAGE_SCHEMAS / "iwxxm"
+    if iwxxm.is_dir() and any(iwxxm.iterdir()):
+        # Require at least one version tree (not only empty placeholder).
+        if any((iwxxm / child).is_dir() for child in iwxxm.iterdir()):
+            return _PACKAGE_SCHEMAS
+    return None
+
+
+def repo_root() -> Path:
+    """
+    Return the monorepo root containing ``vendor/schemas``.
+
+    Honours ``IWXXM_SCHEMAS_ROOT`` parent when set to ``…/vendor/schemas/iwxxm``.
+    """
+    env = os.environ.get("IWXXM_VALIDATE_REPO_ROOT")
+    if env:
+        return Path(env).resolve()
+    schemas_root = os.environ.get("IWXXM_SCHEMAS_ROOT")
+    if schemas_root:
+        path = Path(schemas_root).resolve()
+        # …/vendor/schemas/iwxxm → repo root two parents up from iwxxm
+        if path.name == "iwxxm" and path.parent.name == "schemas":
+            return path.parent.parent.parent
+        return path
+    return _DEFAULT_REPO_ROOT
+
+
+def vendor_iwxxm_root() -> Path:
+    """Return ``iwxxm`` schema root (packaged subset or ``vendor/schemas/iwxxm``)."""
+    packaged = packaged_schemas_root()
+    if packaged is not None:
+        return packaged / "iwxxm"
+    return repo_root() / "vendor" / "schemas" / "iwxxm"
+
+
+def vendor_iwxxm_us_root() -> Path:
+    """Return ``iwxxm-us`` schema root (packaged subset or vendor pin)."""
+    packaged = packaged_schemas_root()
+    if packaged is not None:
+        return packaged / "iwxxm-us"
+    return repo_root() / "vendor" / "schemas" / "iwxxm-us"
+
+
+@lru_cache(maxsize=32)
+def version_dir(iwxxm_version: str) -> Path:
+    """
+    Return the IWXXM version tree (contains ``IWXXM/``).
+
+    Parameters
+    ----------
+    iwxxm_version :
+        Release line such as ``2023-1`` or ``2025-2``.
+    """
+    path = vendor_iwxxm_root() / iwxxm_version
+    if not path.is_dir():
+        raise FileNotFoundError(f"IWXXM version directory not found: {path}")
+    return path
+
+
+def xsd_path(iwxxm_version: str) -> Path:
+    """Return path to ``iwxxm.xsd`` for ``iwxxm_version``."""
+    path = version_dir(iwxxm_version) / "IWXXM" / "iwxxm.xsd"
+    if not path.is_file():
+        raise FileNotFoundError(f"XSD not found for {iwxxm_version}: {path}")
+    return path
+
+
+def schematron_path(iwxxm_version: str) -> Path:
+    """Return path to ``rule/iwxxm.sch`` for ``iwxxm_version``."""
+    path = version_dir(iwxxm_version) / "IWXXM" / "rule" / "iwxxm.sch"
+    if not path.is_file():
+        raise FileNotFoundError(f"Schematron not found for {iwxxm_version}: {path}")
+    return path
+
+
+def codelists_dir(iwxxm_version: str) -> Path:
+    """Return directory of bundled RDF codelists for Schematron ``document()``."""
+    path = version_dir(iwxxm_version) / "IWXXM" / "rule"
+    if not path.is_dir():
+        raise FileNotFoundError(f"Codelists directory not found for {iwxxm_version}: {path}")
+    return path
+
+
+def us_catalog_path() -> Path | None:
+    """
+    Return IWXXM-US catalog path when present.
+
+    Prefers ``3.0/united-states-catalog.xml`` under the vendored / packaged pin.
+    """
+    root = vendor_iwxxm_us_root()
+    candidates = [
+        root / "3.0" / "united-states-catalog.xml",
+        root / "united-states-catalog.xml",
+    ]
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def clear_path_caches() -> None:
+    """Clear cached version directory lookups (tests / after schema sync)."""
+    version_dir.cache_clear()
+
+
+__all__ = [
+    "clear_path_caches",
+    "codelists_dir",
+    "packaged_schemas_root",
+    "repo_root",
+    "schematron_path",
+    "us_catalog_path",
+    "vendor_iwxxm_root",
+    "vendor_iwxxm_us_root",
+    "version_dir",
+    "xsd_path",
+]

iwxxm_validate/schemas/LAST_SYNC.json

@@ -0,0 +1,24 @@
+{
+  "destination": "packages/iwxxm-validate/src/iwxxm_validate/schemas",
+  "iwxxm_versions": [
+    "2023-1",
+    "2025-2"
+  ],
+  "file_counts": {
+    "iwxxm/2023-1": 35,
+    "iwxxm/2025-2": 36,
+    "iwxxm/externalSchema": 263,
+    "iwxxm-us": 7
+  },
+  "total_files": 341,
+  "total_bytes": 5736523,
+  "excluded": [
+    "**/html/**",
+    "**/examples/**",
+    "**/XMI/**",
+    "**/documentation/**",
+    "iwxxm-modelling/**",
+    "iwxxm-translation/**",
+    "iwxxm-codelists/**"
+  ]
+}

iwxxm_validate/schemas/MANIFEST.json

@@ -0,0 +1,25 @@
+{
+  "schema_version": 1,
+  "decision": "E10-34",
+  "related": ["E10-6"],
+  "description": "Runtime IWXXM schema subset for the iwxxm-validate wheel (XSD + Schematron + RDF codelists + externalSchema catalogs + IWXXM-US). Excludes modelling/translation bulk and documentation trees.",
+  "iwxxm_versions": ["2023-1", "2025-2"],
+  "include": {
+    "iwxxm": ["{version}/IWXXM/*.xsd", "{version}/IWXXM/rule/**", "externalSchema/**"],
+    "iwxxm-us": ["**"]
+  },
+  "exclude": [
+    "**/html/**",
+    "**/examples/**",
+    "**/XMI/**",
+    "**/documentation/**",
+    "iwxxm-modelling/**",
+    "iwxxm-translation/**",
+    "iwxxm-codelists/**"
+  ],
+  "notes": [
+    "Codelist RDFs used by Schematron document() live under each version IWXXM/rule/ (not the separate iwxxm-codelists tree).",
+    "externalSchema under iwxxm covers XSD imports (GML/AIXM/W3C); translation bulk is not bundled.",
+    "Sync from monorepo vendor pins via: make sync-iwxxm-validate-schemas"
+  ]
+}