cbpr-usage-rules 0.1.0__py3-none-any.whl

cbpr_rules/helpers.py

@@ -0,0 +1,420 @@
+"""Reusable check builders for the recurring CBPR+ rule patterns.
+
+Each builder returns a ``check(msg, report)`` function, so it can be registered
+directly with the ``@rule`` decorator::
+
+    rule("pacs.008", 2025, "R20", NAME, DESC)(
+        presence_together(BASE, "Nm", "PstlAdr")
+    )
+
+Hand-authored rules with bespoke logic just define ``fn(msg, report)`` directly
+and use the query methods on ParsedMessage. These builders cover the common
+templated patterns ("if X present then Y", "A must equal B", length/code lists)
+so they need only be written once.
+"""
+from __future__ import annotations
+
+import re
+from decimal import Decimal, InvalidOperation
+from typing import Callable, Iterable, Optional, Sequence
+
+from lxml import etree
+
+
+def presence_together(base_path: str, a: str, b: str) -> Callable:
+    """``a`` and ``b`` (relative to each ``base_path``) must be present together."""
+
+    def check(msg, report):
+        for ctx in msg.each(base_path):
+            has_a = msg.present(a, ctx)
+            has_b = msg.present(b, ctx)
+            if has_a != has_b:
+                report(ctx, detail=f"{a} and {b} must be present together")
+
+    return check
+
+
+def requires_if_present(base_path: str, trigger: str, required: str) -> Callable:
+    """If ``trigger`` is present (per ``base_path``), ``required`` must be present."""
+
+    def check(msg, report):
+        for ctx in msg.each(base_path):
+            if msg.present(trigger, ctx) and msg.absent(required, ctx):
+                report(ctx, detail=f"{required} required when {trigger} is present")
+
+    return check
+
+
+def required_when_absent(
+    base_path: str, absent_path: str, required: Sequence[str], mode: str = "all"
+) -> Callable:
+    """When ``absent_path`` is absent, ``required`` paths must be present.
+
+    ``mode="all"`` (default): every path in ``required`` must be present.
+    ``mode="any"``: at least one of ``required`` must be present.
+    """
+
+    def check(msg, report):
+        for ctx in msg.each(base_path):
+            if not msg.absent(absent_path, ctx):
+                continue
+            present = [p for p in required if msg.present(p, ctx)]
+            ok = bool(present) if mode == "any" else len(present) == len(required)
+            if not ok:
+                joiner = " or " if mode == "any" else " and "
+                report(ctx, detail=f"{joiner.join(required)} required when {absent_path} is absent")
+
+    return check
+
+
+def required_when_present(
+    base_path: str, present_path: str, required: Sequence[str], mode: str = "all"
+) -> Callable:
+    """When ``present_path`` is present, ``required`` paths must be present too."""
+
+    def check(msg, report):
+        for ctx in msg.each(base_path):
+            if not msg.present(present_path, ctx):
+                continue
+            found = [p for p in required if msg.present(p, ctx)]
+            ok = bool(found) if mode == "any" else len(found) == len(required)
+            if not ok:
+                joiner = " or " if mode == "any" else " and "
+                report(ctx, detail=f"{joiner.join(required)} required when {present_path} is present")
+
+    return check
+
+
+def mutually_exclusive(base_path: str, paths: Sequence[str]) -> Callable:
+    """At most one of ``paths`` (relative to ``base_path``) may be present."""
+
+    def check(msg, report):
+        for ctx in msg.each(base_path):
+            present = [p for p in paths if msg.present(p, ctx)]
+            if len(present) > 1:
+                report(ctx, detail=f"mutually exclusive: {', '.join(present)}")
+
+    return check
+
+
+def forbidden_when_present(base_path: str, forbidden: str, when: str) -> Callable:
+    """``forbidden`` must not be present when ``when`` is present."""
+
+    def check(msg, report):
+        for ctx in msg.each(base_path):
+            if msg.present(when, ctx) and msg.present(forbidden, ctx):
+                report(ctx, detail=f"{forbidden} cannot be present when {when} is present")
+
+    return check
+
+
+def value_not_in(path: str, forbidden_values: Iterable[str]) -> Callable:
+    """No occurrence of ``path`` may hold a value in ``forbidden_values``."""
+    forbidden = set(forbidden_values)
+
+    def check(msg, report):
+        for node in msg.find(path):
+            val = msg.text_of(node)
+            if val in forbidden:
+                report(node, detail=f"'{val}' is not allowed")
+
+    return check
+
+
+def not_matching_pattern(path: str, pattern: str) -> Callable:
+    """Every occurrence of ``path`` must NOT match ``pattern`` (a forbidden regex)."""
+    import re as _re
+
+    rx = _re.compile(pattern)
+
+    def check(msg, report):
+        for node in msg.find(path):
+            val = msg.text_of(node)
+            if val and rx.fullmatch(val):
+                report(node, detail="value matches a forbidden pattern")
+
+    return check
+
+
+# Structured PostalAddress components (short ISO tags), excluding AddressLine.
+ADDRESS_COMPONENTS = (
+    "Dept", "SubDept", "StrtNm", "BldgNb", "BldgNm", "Flr", "PstBx", "Room",
+    "PstCd", "TwnNm", "TwnLctnNm", "DstrctNm", "CtrySubDvsn", "Ctry",
+)
+
+
+def address_lines_max_length(postal_path: str, limit: int = 35) -> Callable:
+    """CBPR+ "unstructured address" rule.
+
+    When a postal address uses only AddressLine (every structured component
+    absent), each AddressLine must not exceed ``limit`` characters.
+    """
+
+    def check(msg, report):
+        for adr in msg.each(postal_path):
+            if msg.absent("AdrLine", adr):
+                continue
+            if any(msg.present(s, adr) for s in ADDRESS_COMPONENTS):
+                continue
+            for line in msg.find("AdrLine", adr):
+                if len(msg.text_of(line)) > limit:
+                    report(line, detail=f"AddressLine exceeds {limit} characters")
+
+    return check
+
+
+def address_hybrid(postal_path: str) -> Callable:
+    """CBPR+ "hybrid address" rule.
+
+    When AddressLine and any structured component are both present, TownName and
+    Country are mandatory.
+    """
+
+    def check(msg, report):
+        for adr in msg.each(postal_path):
+            if msg.absent("AdrLine", adr):
+                continue
+            if not any(msg.present(s, adr) for s in ADDRESS_COMPONENTS):
+                continue
+            if not (msg.present("TwnNm", adr) and msg.present("Ctry", adr)):
+                report(adr, detail="TownName and Country required for a hybrid address")
+
+    return check
+
+
+def same_value(
+    path_a: str,
+    path_b: str,
+    unless_path: Optional[str] = None,
+    unless_values: Sequence[str] = (),
+) -> Callable:
+    """Every occurrence of ``path_a`` must equal every occurrence of ``path_b``.
+
+    Skipped when ``unless_path`` has any value in ``unless_values`` (e.g. a
+    CopyDuplicate of COPY/CODU). Both anchored (absolute) paths.
+    """
+
+    def check(msg, report):
+        if unless_path is not None and unless_values:
+            if any(v in set(unless_values) for v in msg.values(unless_path)):
+                return
+        a_nodes = msg.find(path_a)
+        b_vals = {msg.text_of(n) for n in msg.find(path_b)}
+        a_vals = {msg.text_of(n) for n in a_nodes}
+        if not a_nodes or not b_vals:
+            return
+        if a_vals != b_vals:
+            target = a_nodes[0]
+            report(target, detail=f"{path_a} must equal {path_b}")
+
+    return check
+
+
+def max_length(path: str, limit: int) -> Callable:
+    """Every occurrence of ``path`` must not exceed ``limit`` characters."""
+
+    def check(msg, report):
+        for node in msg.find(path):
+            if len(msg.text_of(node)) > limit:
+                report(node, detail=f"exceeds {limit} characters")
+
+    return check
+
+
+def code_in(path: str, allowed: Iterable[str]) -> Callable:
+    """Every occurrence of ``path`` must hold a value within ``allowed``."""
+    allowed_set = set(allowed)
+
+    def check(msg, report):
+        for node in msg.find(path):
+            val = msg.text_of(node)
+            if val and val not in allowed_set:
+                report(node, detail=f"'{val}' not in allowed code list")
+
+    return check
+
+
+def must_be_absent(path: str) -> Callable:
+    """``path`` must not be present (element removed by the usage guideline)."""
+
+    def check(msg, report):
+        for node in msg.find(path):
+            report(node, detail="element must not be used")
+
+    return check
+
+
+def each_value_valid(path: str, validator: Callable[[str], bool], label: str) -> Callable:
+    """Every non-empty value at ``path`` must satisfy ``validator`` (e.g. IBAN/BIC)."""
+
+    def check(msg, report):
+        for node in msg.find(path):
+            val = msg.text_of(node)
+            if val and not validator(val):
+                report(node, detail=f"invalid {label}: '{val}'")
+
+    return check
+
+
+# ---------------------------------------------------------------------------
+# Cross-cutting checks promoted from advisory rules (Tier A / Tier B).
+# Each is conservative: it skips when its inputs are absent or ambiguous, so a
+# previously-valid message can never be made to fail spuriously.
+# ---------------------------------------------------------------------------
+
+def header_msg_def_id_matches() -> Callable:
+    """``/AppHdr/MsgDefIdr``, if present, must equal the Document's definition id.
+
+    The expected id is the namespace suffix of the ``<Document>`` element, e.g.
+    ``pacs.009.001.08``. Cross-schema (BAH vs Document); skips if either absent.
+    """
+
+    def check(msg, report):
+        if msg.bah is None or msg.document is None:
+            return
+        nodes = msg.find("/AppHdr/MsgDefIdr")
+        if not nodes:
+            return
+        ns = etree.QName(msg.document).namespace or ""
+        marker = "tech:xsd:"
+        expected = ns.split(marker, 1)[1] if marker in ns else None
+        val = msg.text_of(nodes[0])
+        if expected and val and val != expected:
+            report(nodes[0], detail=f"MsgDefIdr '{val}' does not match the message definition '{expected}'")
+
+    return check
+
+
+def business_msg_id_carries_group_id() -> Callable:
+    """``/AppHdr/BizMsgIdr`` must contain the Document's ``GrpHdr/MsgId`` when present."""
+
+    def check(msg, report):
+        if msg.bah is None or msg.document is None:
+            return
+        bmi = msg.find("/AppHdr/BizMsgIdr")
+        if not bmi:
+            return
+        msgid = None
+        for grp in msg.iter_local("GrpHdr"):
+            kids = msg.find("MsgId", grp)
+            if kids:
+                msgid = msg.text_of(kids[0])
+                break
+        if not msgid:
+            return
+        if msgid not in msg.text_of(bmi[0]):
+            report(bmi[0], detail=f"BizMsgIdr should carry the GroupHeader MsgId '{msgid}'")
+
+    return check
+
+
+def _token_contained(value: str, line: str) -> bool:
+    """True if ``value`` equals ``line`` or appears token-bounded within it."""
+    if value == line:
+        return True
+    return re.search(r"(?<![A-Za-z0-9])" + re.escape(value) + r"(?![A-Za-z0-9])", line) is not None
+
+
+def no_postal_address_duplication(min_len: int = 3) -> Callable:
+    """No structured Postal Address value may be repeated inside an AddressLine.
+
+    Scans every ``PstlAdr`` in the message. Conservative: only flags structured
+    values of at least ``min_len`` characters that appear as a whole AddressLine
+    or as a token-bounded substring of one.
+    """
+
+    def check(msg, report):
+        for adr in msg.iter_local("PstlAdr"):
+            lines = [msg.text_of(line) for line in msg.find("AdrLine", adr)]
+            if not lines:
+                continue
+            for comp in ADDRESS_COMPONENTS:
+                for node in msg.find(comp, adr):
+                    val = msg.text_of(node)
+                    if len(val) < min_len:
+                        continue
+                    if any(_token_contained(val, line) for line in lines):
+                        report(node, detail=f"structured value '{val}' is duplicated in AddressLine")
+
+    return check
+
+
+def bic_presence_exclusive(party_path: str) -> Callable:
+    """For a party: if ``Id/OrgId/AnyBIC`` is present, ``Nm`` and ``PstlAdr`` are not allowed."""
+
+    def check(msg, report):
+        for party in msg.each(party_path):
+            if msg.present("Id/OrgId/AnyBIC", party) and (
+                msg.present("Nm", party) or msg.present("PstlAdr", party)
+            ):
+                report(party, detail="Name/PostalAddress not allowed when AnyBIC is present")
+
+    return check
+
+
+def structured_remittance_max_total(path: str, limit: int = 9000) -> Callable:
+    """Total text (excluding tags) of all Structured Remittance occurrences ≤ ``limit``."""
+
+    def check(msg, report):
+        nodes = msg.find(path)
+        if not nodes:
+            return
+        total = sum(
+            len("".join(t.strip() for t in node.itertext())) for node in nodes
+        )
+        if total > limit:
+            report(nodes[0], detail=f"structured remittance total {total} exceeds {limit} characters")
+
+    return check
+
+
+def charges_required_when_amounts_differ(
+    base_path: str, instructed_amt: str, settlement_amt: str, charges: str
+) -> Callable:
+    """If instructed & settlement amounts share a currency and differ, charges are mandatory.
+
+    All sub-paths are relative to each ``base_path`` (e.g. the transaction).
+    Skips unless both amounts are present with the same ``@Ccy`` and parse cleanly.
+    """
+
+    def check(msg, report):
+        for ctx in msg.each(base_path):
+            inst = msg.find(instructed_amt, ctx)
+            sett = msg.find(settlement_amt, ctx)
+            if not inst or not sett:
+                continue
+            i_ccy, s_ccy = inst[0].get("Ccy"), sett[0].get("Ccy")
+            if not i_ccy or i_ccy != s_ccy:
+                continue
+            try:
+                iv = Decimal(msg.text_of(inst[0]))
+                sv = Decimal(msg.text_of(sett[0]))
+            except (InvalidOperation, ValueError):
+                continue
+            if iv != sv and msg.absent(charges, ctx):
+                report(ctx, detail="ChargesInformation is mandatory when instructed and settlement amounts differ in the same currency")
+
+    return check
+
+
+def amount_equals_sum(total_path: str, parts_path: str, tolerance: str = "0.01") -> Callable:
+    """``total_path`` amount must equal the sum of ``parts_path`` amounts (same currency)."""
+    tol = Decimal(tolerance)
+
+    def check(msg, report):
+        totals = msg.find(total_path)
+        parts = msg.find(parts_path)
+        if not totals or not parts:
+            return
+        ccys = {n.get("Ccy") for n in [totals[0], *parts] if n.get("Ccy")}
+        if len(ccys) > 1:
+            return
+        try:
+            total = Decimal(msg.text_of(totals[0]))
+            summed = sum((Decimal(msg.text_of(p)) for p in parts), Decimal("0"))
+        except (InvalidOperation, ValueError):
+            return
+        if abs(total - summed) > tol:
+            report(totals[0], detail=f"total {total} does not equal the sum of records {summed}")
+
+    return check

cbpr_rules/loader.py

@@ -0,0 +1,77 @@
+"""Parse CBPR+ XML and locate the Business Application Header and Document.
+
+The loader is deliberately tolerant of wrapper tags (``<RequestPayload>``,
+``<DataPDU>``, ``<Saa:Envelope>`` ...): it finds the ``AppHdr`` (head.001) and
+``Document`` elements wherever they sit in the tree, matching by *local name* so
+namespace prefixes and versions never matter.
+"""
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+from lxml import etree
+
+
+def local_name(el) -> Optional[str]:
+    """Local (namespace-stripped) tag name of an element, or None for comments/PIs."""
+    tag = el.tag
+    if not isinstance(tag, str):
+        return None
+    return tag.rsplit("}", 1)[-1]
+
+
+def _parser() -> "etree.XMLParser":
+    # huge_tree for large messages; keep line numbers; never touch the network.
+    return etree.XMLParser(
+        resolve_entities=False,
+        no_network=True,
+        huge_tree=True,
+        remove_comments=False,
+    )
+
+
+def parse_file(path: str) -> "etree._ElementTree":
+    return etree.parse(path, _parser())
+
+
+def parse_string(xml: str) -> "etree._ElementTree":
+    data = xml.encode("utf-8") if isinstance(xml, str) else xml
+    root = etree.fromstring(data, _parser())
+    return etree.ElementTree(root)
+
+
+def locate(tree: "etree._ElementTree") -> Tuple[Optional["etree._Element"], Optional["etree._Element"]]:
+    """Return (app_header, document) elements, found anywhere under the root."""
+    root = tree.getroot()
+    bah = None
+    doc = None
+    for el in root.iter():
+        ln = local_name(el)
+        if ln == "AppHdr" and bah is None:
+            bah = el
+        elif ln == "Document" and doc is None:
+            doc = el
+        if bah is not None and doc is not None:
+            break
+    return bah, doc
+
+
+def detect_message_type(doc: Optional["etree._Element"]) -> Optional[str]:
+    """Derive the base message type (e.g. ``pacs.008``) from the Document namespace.
+
+    Note: business variants (STP/COV/ADV) share a base namespace and cannot be
+    distinguished from the XML alone - callers select those explicitly.
+    """
+    if doc is None:
+        return None
+    qname = etree.QName(doc)
+    ns = qname.namespace or ""
+    marker = "tech:xsd:"
+    if marker in ns:
+        ident = ns.split(marker, 1)[1]  # e.g. pacs.008.001.08
+    else:
+        ident = ns.rsplit(":", 1)[-1]
+    parts = ident.split(".")
+    if len(parts) >= 2:
+        return f"{parts[0]}.{parts[1]}"  # pacs.008
+    return ident or None

cbpr_rules/message.py

@@ -0,0 +1,170 @@
+"""ParsedMessage - namespace-agnostic path access over a CBPR+ message.
+
+Rules are authored against the short ISO 20022 XML-tag paths exactly as they
+appear in the published usage guideline's "XML Path" column, e.g.::
+
+    /AppHdr/Fr/FIId/FinInstnId/BICFI
+    /Document/FIToFICstmrCdtTrf/CdtTrfTxInf/PmtTpInf/InstrPrty
+
+Paths are matched segment-by-segment by *local name*, so namespaces, prefixes
+and wrapper tags are irrelevant. A path beginning with ``AppHdr`` is anchored at
+the Business Application Header; one beginning with ``Document`` at the Document.
+Any other path is treated as relative to a ``context`` element (used inside
+"for each" iterations); a leading segment equal to the context's own name is
+consumed so relative paths can restate the context name, matching the source
+pseudo-code convention.
+"""
+from __future__ import annotations
+
+from typing import List, Optional
+
+from .loader import local_name
+
+
+def _split(path: str) -> List[str]:
+    return [s for s in (seg.strip() for seg in path.strip().strip("/").split("/")) if s]
+
+
+def _children_named(el, name: str) -> List["object"]:
+    out = []
+    for child in el:
+        if local_name(child) == name:
+            out.append(child)
+    return out
+
+
+def _descend(elements: List["object"], segs: List[str]) -> List["object"]:
+    current = list(elements)
+    for seg in segs:
+        nxt: List[object] = []
+        for el in current:
+            nxt.extend(_children_named(el, seg))
+        current = nxt
+        if not current:
+            break
+    return current
+
+
+class ParsedMessage:
+    """A parsed CBPR+ message exposing the BAH and Document for rule checks."""
+
+    def __init__(self, tree, bah, document, message_type=None, year=None):
+        self._tree = tree
+        self.bah = bah
+        self.document = document
+        self.message_type = message_type
+        self.year = year
+
+    # -- element metadata ------------------------------------------------
+    def xpath_of(self, el) -> str:
+        """A readable local-name xpath, e.g. ``/Document/.../IntrBkSttlmAmt``.
+
+        Positional ``[n]`` is added only where same-named siblings exist, so
+        paths stay clean but remain unambiguous for repeated elements.
+        """
+        if el is None:
+            return ""
+        steps = []
+        node = el
+        while node is not None and isinstance(node.tag, str):
+            name = local_name(node)
+            parent = node.getparent()
+            if parent is not None:
+                same = [c for c in parent if local_name(c) == name]
+                if len(same) > 1:
+                    name = f"{name}[{same.index(node) + 1}]"
+            steps.append(name)
+            node = parent
+        return "/" + "/".join(reversed(steps))
+
+    def line_of(self, el) -> Optional[int]:
+        if el is None:
+            return None
+        return getattr(el, "sourceline", None)
+
+    @staticmethod
+    def text_of(el) -> str:
+        if el is None:
+            return ""
+        return (el.text or "").strip()
+
+    def snippet_of(self, el, limit: int = 160) -> str:
+        """A short, namespace-stripped view of the offending element.
+
+        Leaf elements render as ``<Tag attr="v">text</Tag>``; container
+        elements render as ``<Tag> containing {Child1, Child2, ...}`` so the
+        user can see what the file actually has at that location.
+        """
+        if el is None or not isinstance(el.tag, str):
+            return ""
+        name = local_name(el)
+        attrs = " ".join(
+            f'{k.rsplit("}", 1)[-1]}="{v}"' for k, v in el.attrib.items()
+        )
+        head = name + (" " + attrs if attrs else "")
+        children = [local_name(c) for c in el if isinstance(c.tag, str)]
+        if children:
+            shown = ", ".join(children[:8]) + (", ..." if len(children) > 8 else "")
+            out = f"<{head}> containing {{{shown}}}"
+        else:
+            text = self.text_of(el)
+            out = f"<{head}>{text}</{name}>"
+        return out if len(out) <= limit else out[: limit - 1] + "…"
+
+    # -- path queries ----------------------------------------------------
+    def find(self, path: str, context=None) -> List["object"]:
+        """Return all elements matching ``path`` (anchored or relative)."""
+        segs = _split(path)
+        if not segs:
+            return [context] if context is not None else []
+        head = segs[0]
+        if head == "AppHdr" or head.startswith("BusinessApplicationHeader"):
+            return _descend([self.bah], segs[1:]) if self.bah is not None else []
+        if head == "Document":
+            return _descend([self.document], segs[1:]) if self.document is not None else []
+        # relative to context
+        if context is not None:
+            if local_name(context) == head:
+                return _descend([context], segs[1:])
+            return _descend([context], segs)
+        return []
+
+    def each(self, path: str, context=None) -> List["object"]:
+        """Iteration helper - same as find(), named for "for each [path]" rules."""
+        return self.find(path, context)
+
+    def first(self, path: str, context=None):
+        matches = self.find(path, context)
+        return matches[0] if matches else None
+
+    def present(self, path: str, context=None) -> bool:
+        return bool(self.find(path, context))
+
+    def absent(self, path: str, context=None) -> bool:
+        return not self.present(path, context)
+
+    def values(self, path: str, context=None) -> List[str]:
+        """Stripped text content of every element matching ``path``."""
+        return [self.text_of(el) for el in self.find(path, context)]
+
+    def attr_nodes(self, path: str, attr: str, context=None):
+        """(element, attribute value) for every element matching ``path``.
+
+        Used for XML attributes such as the currency on an amount (``@Ccy``).
+        """
+        return [(el, el.get(attr)) for el in self.find(path, context)]
+
+    def iter_local(self, name: str, roots=None):
+        """Yield every descendant (at any depth) with local tag ``name``.
+
+        Scans the BAH and Document by default - used by cross-cutting checks
+        that apply wherever an element occurs (e.g. every PostalAddress).
+        """
+        if roots is None:
+            roots = [r for r in (self.bah, self.document) if r is not None]
+        for root in roots:
+            if root is None:
+                continue
+            for el in root.iter():
+                if local_name(el) == name:
+                    yield el