cbpr-validate 1.0.0__py3-none-any.whl

cbpr_validate/__init__.py

@@ -0,0 +1,18 @@
+"""cbpr-validate: validate ISO 20022 CBPR+ messages against the usage guidelines.
+
+    from cbpr_validate import validate_file
+
+    result = validate_file("payment.xml")
+    result.is_compliant, result.errors, result.warnings
+"""
+
+from cbpr_validate.core import validate_bytes, validate_file, validate_string
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "__version__",
+    "validate_bytes",
+    "validate_file",
+    "validate_string",
+]

cbpr_validate/api/main.py

@@ -0,0 +1,120 @@
+"""FastAPI service: ``POST /validate`` and ``POST /correlate``.
+
+Like the CLI, this is a shell over the library. Both endpoints build their
+response from the same ``report.json_report`` envelopes the CLI's ``--format
+json`` prints, so the two interfaces cannot disagree about a message. The
+response models below exist to give the OpenAPI document real schemas rather
+than a bare ``object`` - their fields mirror those envelopes exactly, and a test
+pins that correspondence.
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel, Field
+
+from cbpr_validate import __version__
+from cbpr_validate.match.matcher import UnsupportedPairError, correlate
+from cbpr_validate.match.result import Direction, MatchKey, MessageRef, Scenario
+from cbpr_validate.model.finding import Finding
+from cbpr_validate.model.payment import Payment
+from cbpr_validate.parsers.parse import UnsupportedMessageTypeError, parse_message
+from cbpr_validate.report.json_report import match_to_dict, validation_to_dict
+from cbpr_validate.rules.registry import run_all
+
+app = FastAPI(
+    title="cbpr-validate",
+    version=__version__,
+    summary="Validate ISO 20022 CBPR+ messages against the usage guidelines, not just the XSD.",
+    description=(
+        "Two operations. `/validate` runs every registered usage-guideline rule "
+        "against a single message. `/correlate` checks whether two specific "
+        "messages correctly reference each other (pairwise and stateless - no "
+        "message store).\n\n"
+        "**XSD-valid is not CBPR+-compliant.** The optional XSD layer is CLI-only: "
+        "it needs schemas this project does not redistribute."
+    ),
+)
+
+
+class ValidateRequest(BaseModel):
+    message: str = Field(
+        ...,
+        description="The ISO 20022 message as XML (pacs.008, pacs.009, pacs.002 or pacs.004).",
+    )
+
+
+class CorrelateRequest(BaseModel):
+    message_a: str = Field(..., description="First message, as XML.")
+    message_b: str = Field(..., description="Second message, as XML. Order does not matter.")
+    direction: Direction | None = Field(
+        None,
+        description=(
+            "Required for a pacs.002 <-> pacs.008 pair: whether the caller sent the "
+            "pacs.008 (outbound) or received it (inbound). Never inferred from BICs."
+        ),
+    )
+
+
+class ValidationResponse(BaseModel):
+    """Mirrors ``report.json_report.validation_to_dict``."""
+
+    is_compliant: bool
+    summary: dict[str, int]
+    findings: list[Finding]
+
+
+class MatchResponse(BaseModel):
+    """Mirrors ``report.json_report.match_to_dict``."""
+
+    matched: bool
+    is_consistent: bool
+    scenario: Scenario
+    match_key: MatchKey
+    uetr: str | None
+    direction: Direction | None
+    fallback_used: bool
+    linked_fields: list[str]
+    message_a: MessageRef
+    message_b: MessageRef
+    summary: dict[str, int]
+    mismatches: list[Finding]
+
+
+class HealthResponse(BaseModel):
+    status: str
+    version: str
+
+
+def _parse(xml: str, label: str) -> Payment:
+    try:
+        return parse_message(xml.encode())
+    except UnsupportedMessageTypeError as exc:
+        raise HTTPException(status_code=400, detail=f"{label}: {exc}") from exc
+
+
+@app.get("/health", response_model=HealthResponse, tags=["meta"])
+def health() -> HealthResponse:
+    """Liveness probe."""
+    return HealthResponse(status="ok", version=__version__)
+
+
+@app.post("/validate", response_model=ValidationResponse, tags=["validate"])
+def validate(request: ValidateRequest) -> ValidationResponse:
+    """Run every registered CBPR+ usage-guideline rule against one message."""
+    payment = _parse(request.message, "message")
+    return ValidationResponse(**validation_to_dict(run_all(payment)))
+
+
+@app.post("/correlate", response_model=MatchResponse, tags=["correlate"])
+def correlate_messages(request: CorrelateRequest) -> MatchResponse:
+    """Check whether two specific messages correctly reference each other."""
+    a = _parse(request.message_a, "message_a")
+    b = _parse(request.message_b, "message_b")
+    try:
+        result = correlate(a, b, request.direction)
+    except UnsupportedPairError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except ValueError as exc:  # missing direction for the pacs.002 scenario
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    return MatchResponse(**match_to_dict(result))

cbpr_validate/cli.py

@@ -0,0 +1,247 @@
+"""Typer CLI: ``cbpr-validate check`` and ``cbpr-validate match``.
+
+The CLI is a thin shell. Parsing, rule execution, correlation and formatting all
+live in the library, so the CLI and the API cannot drift apart in what they
+report - only in how they are invoked.
+
+Exit codes (stable, so this is usable as a CI gate):
+
+* ``0`` - clean, or findings below the ``--fail-on`` threshold
+* ``1`` - findings at or above the threshold / the two messages do not correlate
+* ``2`` - the input could not be used (unreadable, unparseable, no XSD, bad pair)
+"""
+
+from __future__ import annotations
+
+import sys
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from cbpr_validate.core import validate_file as validate_message_file
+from cbpr_validate.match.matcher import UnsupportedPairError, correlate
+from cbpr_validate.match.result import Direction
+from cbpr_validate.model.payment import Payment
+from cbpr_validate.model.validation_result import ValidationResult
+from cbpr_validate.parsers.detect import detect_message_type
+from cbpr_validate.parsers.parse import UnsupportedMessageTypeError, parse_message
+from cbpr_validate.report.json_report import match_to_json, validation_to_json
+from cbpr_validate.report.junit_report import match_to_junit, validation_to_junit
+from cbpr_validate.report.text_report import match_to_text, validation_to_text
+from cbpr_validate.rules.registry import run_all
+from cbpr_validate.schema.xsd import XsdUnavailableError, validate_against_xsd
+
+app = typer.Typer(
+    help="cbpr-validate: ISO 20022 CBPR+ usage-guideline validator",
+    no_args_is_help=True,
+)
+
+EXIT_OK = 0
+EXIT_FINDINGS = 1
+EXIT_INPUT_ERROR = 2
+
+
+class OutputFormat(StrEnum):
+    TEXT = "text"
+    JSON = "json"
+    JUNIT = "junit"
+
+
+class FailOn(StrEnum):
+    ERROR = "error"
+    WARN = "warn"
+    NEVER = "never"
+
+
+class FailOnLevel(StrEnum):
+    """Threshold for `validate`. Narrower on purpose: a gate wants a floor, not
+    an off switch, so there is no "never" here."""
+
+    ERROR = "error"
+    WARNING = "warning"
+
+
+MessageArgument = Annotated[
+    Path,
+    typer.Argument(
+        exists=True,
+        dir_okay=False,
+        readable=True,
+        help="Path to an ISO 20022 message (XML).",
+    ),
+]
+FormatOption = Annotated[
+    OutputFormat, typer.Option("--format", "-f", help="Output format.")
+]
+
+
+def _read(path: Path) -> bytes:
+    try:
+        return path.read_bytes()
+    except OSError as exc:  # pragma: no cover - argument callback catches most cases
+        typer.echo(f"error: could not read {path}: {exc}", err=True)
+        raise typer.Exit(EXIT_INPUT_ERROR) from exc
+
+
+def _parse(path: Path) -> Payment:
+    try:
+        return parse_message(_read(path))
+    except UnsupportedMessageTypeError as exc:
+        typer.echo(f"error: {path}: {exc}", err=True)
+        raise typer.Exit(EXIT_INPUT_ERROR) from exc
+
+
+def _should_fail(result: ValidationResult, fail_on: FailOn) -> bool:
+    if fail_on is FailOn.NEVER:
+        return False
+    if fail_on is FailOn.WARN:
+        return bool(result.errors or result.warnings)
+    return bool(result.errors)
+
+
+@app.command()
+def validate(
+    message: MessageArgument,
+    as_json: Annotated[
+        bool, typer.Option("--json", help="Emit the result as JSON instead of text.")
+    ] = False,
+    fail_on: Annotated[
+        FailOnLevel,
+        typer.Option("--fail-on", help="Lowest severity that makes this command exit 1."),
+    ] = FailOnLevel.ERROR,
+) -> None:
+    """Validate a message against the CBPR+ usage guidelines.
+
+    Goes through ``cbpr_validate.core.validate_file``, so an unreadable,
+    malformed or unrecognised document is reported as an ``ORCH-*`` finding and
+    still exits 1 - never a traceback.
+    """
+    result = validate_message_file(message)
+
+    if as_json:
+        typer.echo(validation_to_json(result))
+    else:
+        for finding in result.findings:
+            line = f"{finding.rule_id} | {finding.severity.value} | {finding.message}"
+            if finding.location:
+                line += f" | {finding.location}"
+            typer.echo(line)
+        errors = len(result.errors)
+        warnings = len(result.warnings)
+        infos = len(result.findings) - errors - warnings
+        verdict = "COMPLIANT" if result.is_compliant else "NOT COMPLIANT"
+        typer.echo(
+            f"{len(result.findings)} finding(s): {errors} error, {warnings} warn, "
+            f"{infos} info - {verdict}"
+        )
+
+    tripped = result.errors or (fail_on is FailOnLevel.WARNING and result.warnings)
+    raise typer.Exit(EXIT_FINDINGS if tripped else EXIT_OK)
+
+
+@app.command()
+def check(
+    message: MessageArgument,
+    output_format: FormatOption = OutputFormat.TEXT,
+    xsd: Annotated[
+        bool,
+        typer.Option(
+            "--xsd/--no-xsd",
+            help="Also run the optional XSD structural layer (requires your own schemas).",
+        ),
+    ] = False,
+    xsd_dir: Annotated[
+        Path | None,
+        typer.Option(
+            "--xsd-dir",
+            help="Directory holding your licensed ISO 20022 schemas. "
+            "Defaults to $CBPR_VALIDATE_XSD_DIR.",
+        ),
+    ] = None,
+    fail_on: Annotated[
+        FailOn, typer.Option("--fail-on", help="Severity that makes this command exit 1.")
+    ] = FailOn.ERROR,
+) -> None:
+    """Validate one message against the CBPR+ usage guidelines."""
+    raw = _read(message)
+    payment = _parse(message)
+    result = run_all(payment)
+
+    if xsd:
+        try:
+            result.findings.extend(
+                validate_against_xsd(raw, detect_message_type(raw), xsd_dir=xsd_dir)
+            )
+        except XsdUnavailableError as exc:
+            typer.echo(f"error: {exc}", err=True)
+            raise typer.Exit(EXIT_INPUT_ERROR) from exc
+
+    source = message.name
+    if output_format is OutputFormat.JSON:
+        typer.echo(validation_to_json(result))
+    elif output_format is OutputFormat.JUNIT:
+        typer.echo(validation_to_junit(result, source=source))
+    else:
+        typer.echo(validation_to_text(result, source=source))
+
+    raise typer.Exit(EXIT_FINDINGS if _should_fail(result, fail_on) else EXIT_OK)
+
+
+@app.command()
+def match(
+    message_a: MessageArgument,
+    message_b: MessageArgument,
+    direction: Annotated[
+        Direction | None,
+        typer.Option(
+            "--direction",
+            help="Required for pacs.002 <-> pacs.008: whether YOU sent the pacs.008 "
+            "(outbound) or received it (inbound). Never inferred from BICs.",
+        ),
+    ] = None,
+    output_format: FormatOption = OutputFormat.TEXT,
+) -> None:
+    """Correlate two related messages (COV<->008, 002<->008, 004<->008)."""
+    a = _parse(message_a)
+    b = _parse(message_b)
+
+    try:
+        result = correlate(a, b, direction)
+    except (UnsupportedPairError, ValueError) as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(EXIT_INPUT_ERROR) from exc
+
+    if output_format is OutputFormat.JSON:
+        typer.echo(match_to_json(result))
+    elif output_format is OutputFormat.JUNIT:
+        typer.echo(match_to_junit(result))
+    else:
+        typer.echo(match_to_text(result))
+
+    raise typer.Exit(EXIT_OK if result.is_consistent else EXIT_FINDINGS)
+
+
+@app.command()
+def version() -> None:
+    """Print the installed version."""
+    from cbpr_validate import __version__
+
+    typer.echo(__version__)
+
+
+def main() -> None:
+    # Findings quote message content verbatim, and a real payment can carry
+    # characters the console encoding cannot represent (a non-Latin party name,
+    # say). Degrade those to a placeholder rather than dying with
+    # UnicodeEncodeError halfway through a report.
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            reconfigure(errors="replace")
+    app()
+
+
+if __name__ == "__main__":  # pragma: no cover - console-script entry point
+    main()

cbpr_validate/codesets/data/iso20022_codesets.json

@@ -0,0 +1,276 @@
+{
+  "ExternalPurpose1Code": [
+    "CORT",
+    "DVPM",
+    "SALA",
+    "TREA",
+    "CASH"
+  ],
+  "ExternalCategoryPurpose1Code": [
+    "CASH",
+    "CCRD",
+    "CPRC",
+    "SALA"
+  ],
+  "ExternalStatusReason1Code": [
+    "ACCP",
+    "RJCT",
+    "PDNG"
+  ],
+  "ExternalReturnReason1Code": [
+    "CURR",
+    "DNCL",
+    "CANC"
+  ],
+  "ISO3166-1-alpha-2": [
+    "AD",
+    "AE",
+    "AF",
+    "AG",
+    "AI",
+    "AL",
+    "AM",
+    "AO",
+    "AQ",
+    "AR",
+    "AS",
+    "AT",
+    "AU",
+    "AW",
+    "AX",
+    "AZ",
+    "BA",
+    "BB",
+    "BD",
+    "BE",
+    "BF",
+    "BG",
+    "BH",
+    "BI",
+    "BJ",
+    "BL",
+    "BM",
+    "BN",
+    "BO",
+    "BQ",
+    "BR",
+    "BS",
+    "BT",
+    "BV",
+    "BW",
+    "BY",
+    "BZ",
+    "CA",
+    "CC",
+    "CD",
+    "CF",
+    "CG",
+    "CH",
+    "CI",
+    "CK",
+    "CL",
+    "CM",
+    "CN",
+    "CO",
+    "CR",
+    "CU",
+    "CV",
+    "CW",
+    "CX",
+    "CY",
+    "CZ",
+    "DE",
+    "DJ",
+    "DK",
+    "DM",
+    "DO",
+    "DZ",
+    "EC",
+    "EE",
+    "EG",
+    "EH",
+    "ER",
+    "ES",
+    "ET",
+    "FI",
+    "FJ",
+    "FK",
+    "FM",
+    "FO",
+    "FR",
+    "GA",
+    "GB",
+    "GD",
+    "GE",
+    "GF",
+    "GG",
+    "GH",
+    "GI",
+    "GL",
+    "GM",
+    "GN",
+    "GP",
+    "GQ",
+    "GR",
+    "GS",
+    "GT",
+    "GU",
+    "GW",
+    "GY",
+    "HK",
+    "HM",
+    "HN",
+    "HR",
+    "HT",
+    "HU",
+    "ID",
+    "IE",
+    "IL",
+    "IM",
+    "IN",
+    "IO",
+    "IQ",
+    "IR",
+    "IS",
+    "IT",
+    "JE",
+    "JM",
+    "JO",
+    "JP",
+    "KE",
+    "KG",
+    "KH",
+    "KI",
+    "KM",
+    "KN",
+    "KP",
+    "KR",
+    "KW",
+    "KY",
+    "KZ",
+    "LA",
+    "LB",
+    "LC",
+    "LI",
+    "LK",
+    "LR",
+    "LS",
+    "LT",
+    "LU",
+    "LV",
+    "LY",
+    "MA",
+    "MC",
+    "MD",
+    "ME",
+    "MF",
+    "MG",
+    "MH",
+    "MK",
+    "ML",
+    "MM",
+    "MN",
+    "MO",
+    "MP",
+    "MQ",
+    "MR",
+    "MS",
+    "MT",
+    "MU",
+    "MV",
+    "MW",
+    "MX",
+    "MY",
+    "MZ",
+    "NA",
+    "NC",
+    "NE",
+    "NF",
+    "NG",
+    "NI",
+    "NL",
+    "NO",
+    "NP",
+    "NR",
+    "NU",
+    "NZ",
+    "OM",
+    "PA",
+    "PE",
+    "PF",
+    "PG",
+    "PH",
+    "PK",
+    "PL",
+    "PM",
+    "PN",
+    "PR",
+    "PS",
+    "PT",
+    "PW",
+    "PY",
+    "QA",
+    "RE",
+    "RO",
+    "RS",
+    "RU",
+    "RW",
+    "SA",
+    "SB",
+    "SC",
+    "SD",
+    "SE",
+    "SG",
+    "SH",
+    "SI",
+    "SJ",
+    "SK",
+    "SL",
+    "SM",
+    "SN",
+    "SO",
+    "SR",
+    "SS",
+    "ST",
+    "SV",
+    "SX",
+    "SY",
+    "SZ",
+    "TC",
+    "TD",
+    "TF",
+    "TG",
+    "TH",
+    "TJ",
+    "TK",
+    "TL",
+    "TM",
+    "TN",
+    "TO",
+    "TR",
+    "TT",
+    "TV",
+    "TW",
+    "TZ",
+    "UA",
+    "UG",
+    "UM",
+    "US",
+    "UY",
+    "UZ",
+    "VA",
+    "VC",
+    "VE",
+    "VG",
+    "VI",
+    "VN",
+    "VU",
+    "WF",
+    "WS",
+    "YE",
+    "YT",
+    "ZA",
+    "ZM",
+    "ZW"
+  ]
+}

cbpr_validate/codesets/loader.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+# Revision marker rather than a new date: the ISO 20022 External Code Set
+# vintage is unchanged: only the ISO 3166-1 alpha-2 list was completed, from a
+# 10-country stub to the full 249 officially assigned codes. Dating it 2026-08
+# would claim a code-set release that did not happen.
+SNAPSHOT_VERSION = "iso20022-codesets-2026-06-r2"
+_DATA_PATH = Path(__file__).resolve().parent / "data" / "iso20022_codesets.json"
+
+
+def _load_snapshot() -> dict[str, set[str]]:
+    if not _DATA_PATH.exists():
+        return {}
+    with _DATA_PATH.open("r", encoding="utf-8") as handle:
+        raw = json.load(handle)
+    return {name: set(values) for name, values in raw.items()}
+
+
+_CODES = _load_snapshot()
+
+
+def get_snapshot_version() -> str:
+    return SNAPSHOT_VERSION
+
+
+def is_valid(set_name: str, code: str) -> bool:
+    values = _CODES.get(set_name, set())
+    return code in values
+
+
+def get_codes(set_name: str) -> set[str]:
+    return set(_CODES.get(set_name, set()))