cbpr-usage-rules 0.5.0__tar.gz → 0.6.0__tar.gz

{cbpr_usage_rules-0.5.0 → cbpr_usage_rules-0.6.0}/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0]
+
+### Added
+- Rule listings now show the **affected XPaths** for each rule, so agents can see
+  exactly which field(s) a rule constrains (concrete element paths and `@attribute`
+  targets, or a `//Name` wildcard). Shown by default in `cbpr-validate --list` /
+  `--enforced` (text + JSON) and via `list_rules(..., with_xpaths=True)`. Paths are
+  derived by running each rule against the bundled example messages.
+
 ## [0.5.0]
 
 ### Added

{cbpr_usage_rules-0.5.0/src/cbpr_usage_rules.egg-info → cbpr_usage_rules-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cbpr-usage-rules
-Version: 0.5.0
+Version: 0.6.0
 Summary: Validate ISO 20022 CBPR+ XML messages against SWIFT usage (business) rules.
 Author: Pete Houghton
 License: MIT License
@@ -282,6 +282,7 @@ matching is by local name, so namespace prefixes never matter.
 cbpr_rules.available(2025)              # -> ['camt.052', 'pacs.008', ...]
 cbpr_rules.list_rules(2025, "pacs.008") # -> [{rule_number, name, description, severity, enforced}, ...]
 cbpr_rules.list_rules(2025, "pacs.008", enforced_only=True)  # only the enforceable rules
+cbpr_rules.list_rules(2025, "pacs.008", with_xpaths=True)    # + "xpaths" each rule affects
 ```
 
 ```bash
@@ -290,6 +291,24 @@ cbpr-validate --year 2025 --type pacs.008 --list               # all rules
 cbpr-validate --year 2025 --type pacs.008 --enforced           # enforceable rules only
 ```
 
+The `--list` / `--enforced` output (and `with_xpaths=True`) annotates each rule with
+the **concrete fields it affects**, so you can see exactly which element/attribute a
+rule constrains — handy when several fields share a name (e.g. many `Ctry` fields, but
+a rule targets only one):
+
+```text
+pacs.008:VAL-IBAN - CBPR_Valid_IBAN
+    //IBAN
+pacs.008:VAL-BIC - CBPR_Valid_Agent_BIC
+    /Document/FIToFICstmrCdtTrf/CdtTrfTxInf/InstgAgt/FinInstnId/BICFI
+pacs.008:R41 - CBPR_Interbank_Settlement_Currency_FormalRule
+    /Document/FIToFICstmrCdtTrf/CdtTrfTxInf/IntrBkSttlmAmt/@Ccy
+```
+
+Paths are derived by running each rule against the bundled example messages
+(best-effort): concrete element paths and `@attribute` targets where present, or a
+`//Name` wildcard for a datatype rule whose element isn't in the examples.
+
 ### Algorithmic field validation
 
 Beyond the published rules, the following formats are validated with their

{cbpr_usage_rules-0.5.0 → cbpr_usage_rules-0.6.0}/README.md

@@ -227,6 +227,7 @@ matching is by local name, so namespace prefixes never matter.
 cbpr_rules.available(2025)              # -> ['camt.052', 'pacs.008', ...]
 cbpr_rules.list_rules(2025, "pacs.008") # -> [{rule_number, name, description, severity, enforced}, ...]
 cbpr_rules.list_rules(2025, "pacs.008", enforced_only=True)  # only the enforceable rules
+cbpr_rules.list_rules(2025, "pacs.008", with_xpaths=True)    # + "xpaths" each rule affects
 ```
 
 ```bash
@@ -235,6 +236,24 @@ cbpr-validate --year 2025 --type pacs.008 --list               # all rules
 cbpr-validate --year 2025 --type pacs.008 --enforced           # enforceable rules only
 ```
 
+The `--list` / `--enforced` output (and `with_xpaths=True`) annotates each rule with
+the **concrete fields it affects**, so you can see exactly which element/attribute a
+rule constrains — handy when several fields share a name (e.g. many `Ctry` fields, but
+a rule targets only one):
+
+```text
+pacs.008:VAL-IBAN - CBPR_Valid_IBAN
+    //IBAN
+pacs.008:VAL-BIC - CBPR_Valid_Agent_BIC
+    /Document/FIToFICstmrCdtTrf/CdtTrfTxInf/InstgAgt/FinInstnId/BICFI
+pacs.008:R41 - CBPR_Interbank_Settlement_Currency_FormalRule
+    /Document/FIToFICstmrCdtTrf/CdtTrfTxInf/IntrBkSttlmAmt/@Ccy
+```
+
+Paths are derived by running each rule against the bundled example messages
+(best-effort): concrete element paths and `@attribute` targets where present, or a
+`//Name` wildcard for a datatype rule whose element isn't in the examples.
+
 ### Algorithmic field validation
 
 Beyond the published rules, the following formats are validated with their

{cbpr_usage_rules-0.5.0 → cbpr_usage_rules-0.6.0}/src/cbpr_rules/__init__.py

@@ -4,7 +4,7 @@ This package is AI generated. See the README for details and caveats.
 """
 from __future__ import annotations
 
-__version__ = "0.5.0"
+__version__ = "0.6.0"
 
 from .models import Rule, Severity, Violation
 from .engine import (

{cbpr_usage_rules-0.5.0 → cbpr_usage_rules-0.6.0}/src/cbpr_rules/cli.py

@@ -270,13 +270,17 @@ def main(argv: Optional[List[str]] = None) -> int:
         if args.year is None or args.msgtype is None:
             print("error: --year and --type are required for --list", file=sys.stderr)
             return 2
-        rules = list_rules(args.year, args.msgtype, enforced_only=args.enforced)
+        rules = list_rules(
+            args.year, args.msgtype, enforced_only=args.enforced, with_xpaths=True
+        )
         if args.json:
             print(json.dumps(rules, indent=2))
         else:
             for r in rules:
                 flag = "" if r["enforced"] else " (advisory)"
                 print(f"{r['rule_number']} - {r['name']}{flag}")
+                for xp in r.get("xpaths", []):
+                    print(f"    {xp}")
         return 0
 
     if args.year is None:

{cbpr_usage_rules-0.5.0 → cbpr_usage_rules-0.6.0}/src/cbpr_rules/engine.py

@@ -95,15 +95,64 @@ def validate_string(xml: str, year: int, msgtype: Optional[str] = None, xsd=None
     return _validate_tree(tree, year, msgtype, xsd)
 
 
-def list_rules(year: int, msgtype: str, enforced_only: bool = False) -> List[dict]:
+def _drop_redundant_bare_paths(paths: set) -> List[str]:
+    """Tidy captured paths: drop a bare element path when an ``@attribute`` variant
+    exists, and a ``//Name`` wildcard when concrete paths for that name exist."""
+    attr_bases = {p.rsplit("/@", 1)[0] for p in paths if "/@" in p}
+    wild_names = {p[2:] for p in paths if p.startswith("//")}
+    concrete = {p.rsplit("/", 1)[-1].lstrip("@") for p in paths if not p.startswith("//")}
+    kept = set()
+    for p in paths:
+        if p.startswith("//") and p[2:] in concrete:
+            continue
+        if "/@" not in p and p in attr_bases:
+            continue
+        kept.add(p)
+    return sorted(kept)
+
+
+def rule_xpaths(year: int, msgtype: str) -> dict:
+    """Map each rule_number to the concrete xpaths it touches.
+
+    Derived by running each rule against the bundled min+max example messages
+    and recording the fields its queries read (best-effort; a field absent from
+    both examples and read only inside a non-firing branch may be missed).
+    """
+    rules = load_rules(year, msgtype)
+    captured = {r.rule_number: set() for r in rules}
+    for variant in ("min", "max"):
+        try:
+            xml = example_message(year, msgtype, variant)
+            tree = loader.parse_string(xml)
+        except Exception:
+            continue
+        bah, doc = loader.locate(tree)
+        msg = ParsedMessage(tree, bah, doc, message_type=msgtype, year=year)
+        for r in rules:
+            if not r.enforced:
+                continue
+            with msg.record() as paths:
+                r.run(msg)
+            captured[r.rule_number] |= paths
+    return {num: _drop_redundant_bare_paths(p) for num, p in captured.items()}
+
+
+def list_rules(
+    year: int, msgtype: str, enforced_only: bool = False, with_xpaths: bool = False
+) -> List[dict]:
     """Return metadata for the rules registered for a (year, message type).
 
     With ``enforced_only=True`` only the enforceable (mechanically-checked) rules
-    are returned, omitting advisory/catalogue-only ones.
+    are returned. With ``with_xpaths=True`` each rule dict gains an ``"xpaths"``
+    list of the concrete fields it affects (see ``rule_xpaths``).
     """
     rules = [r.to_dict() for r in load_rules(year, msgtype)]
     if enforced_only:
         rules = [r for r in rules if r["enforced"]]
+    if with_xpaths:
+        paths = rule_xpaths(year, msgtype)
+        for r in rules:
+            r["xpaths"] = paths.get(r["rule_number"], [])
     return rules
 
 

{cbpr_usage_rules-0.5.0 → cbpr_usage_rules-0.6.0}/src/cbpr_rules/message.py

@@ -16,10 +16,14 @@ pseudo-code convention.
 """
 from __future__ import annotations
 
+import re
+from contextlib import contextmanager
 from typing import List, Optional
 
 from .loader import local_name
 
+_INDEX_RE = re.compile(r"\[\d+\]")
+
 
 def _split(path: str) -> List[str]:
     return [s for s in (seg.strip() for seg in path.strip().strip("/").split("/")) if s]
@@ -54,6 +58,53 @@ class ParsedMessage:
         self.document = document
         self.message_type = message_type
         self.year = year
+        self._rec: Optional[set] = None  # active path recorder, or None
+
+    # -- path recording (for "which fields does a rule touch?") ----------
+    @contextmanager
+    def record(self):
+        """Within this block, collect the normalized xpaths the queries touch."""
+        prev = self._rec
+        self._rec = set()
+        try:
+            yield self._rec
+        finally:
+            self._rec = prev
+
+    def _normalize(self, xpath: str) -> str:
+        """Strip positional ``[n]`` and re-root at /Document or /AppHdr."""
+        xpath = _INDEX_RE.sub("", xpath)
+        segs = xpath.strip("/").split("/")
+        for anchor in ("Document", "AppHdr"):
+            if anchor in segs:
+                return "/" + "/".join(segs[segs.index(anchor):])
+        return xpath
+
+    def _record_elements(self, elements, attr: Optional[str] = None) -> None:
+        if self._rec is None:
+            return
+        for el in elements:
+            if not isinstance(el.tag, str):
+                continue
+            path = self._normalize(self.xpath_of(el))
+            self._rec.add(path + "/@" + attr if attr else path)
+
+    def _record_intent(self, segs: List[str], context) -> None:
+        """Record the intended anchored path of a query, even if it matched nothing."""
+        if self._rec is None or not segs:
+            return
+        head = segs[0]
+        if head == "AppHdr" or head.startswith("BusinessApplicationHeader"):
+            anchored = "/AppHdr/" + "/".join(segs[1:])
+        elif head == "Document":
+            anchored = "/Document/" + "/".join(segs[1:])
+        elif context is not None:
+            rest = segs[1:] if local_name(context) == head else segs
+            base = self._normalize(self.xpath_of(context))
+            anchored = base + ("/" + "/".join(rest) if rest else "")
+        else:
+            return
+        self._rec.add(anchored.rstrip("/"))
 
     # -- element metadata ------------------------------------------------
     def xpath_of(self, el) -> str:
@@ -119,15 +170,17 @@ class ParsedMessage:
             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 []
+            result = _descend([self.bah], segs[1:]) if self.bah is not None else []
+        elif head == "Document":
+            result = _descend([self.document], segs[1:]) if self.document is not None else []
+        elif context is not None:  # relative to context
+            rest = segs[1:] if local_name(context) == head else segs
+            result = _descend([context], rest)
+        else:
+            result = []
+        self._record_elements(result)
+        self._record_intent(segs, context)
+        return result
 
     def each(self, path: str, context=None) -> List["object"]:
         """Iteration helper - same as find(), named for "for each [path]" rules."""
@@ -152,7 +205,9 @@ class ParsedMessage:
 
         Used for XML attributes such as the currency on an amount (``@Ccy``).
         """
-        return [(el, el.get(attr)) for el in self.find(path, context)]
+        nodes = self.find(path, context)
+        self._record_elements(nodes, attr=attr)
+        return [(el, el.get(attr)) for el in nodes]
 
     def iter_local(self, name: str, roots=None):
         """Yield every descendant (at any depth) with local tag ``name``.
@@ -160,6 +215,8 @@ class ParsedMessage:
         Scans the BAH and Document by default - used by cross-cutting checks
         that apply wherever an element occurs (e.g. every PostalAddress).
         """
+        if self._rec is not None:
+            self._rec.add(f"//{name}")  # wildcard intent (dropped if concrete paths found)
         if roots is None:
             roots = [r for r in (self.bah, self.document) if r is not None]
         for root in roots:
@@ -167,4 +224,18 @@ class ParsedMessage:
                 continue
             for el in root.iter():
                 if local_name(el) == name:
+                    self._record_elements([el])
                     yield el
+
+    def iter_attr(self, attr: str):
+        """Yield (element, value) for every element carrying ``attr`` anywhere.
+
+        Cross-cutting equivalent of ``attr_nodes`` for attributes like ``@Ccy``.
+        """
+        for root in (self.bah, self.document):
+            if root is None:
+                continue
+            for el in root.iter():
+                if isinstance(el.tag, str) and el.get(attr) is not None:
+                    self._record_elements([el], attr=attr)
+                    yield el, el.get(attr)

{cbpr_usage_rules-0.5.0 → cbpr_usage_rules-0.6.0}/src/cbpr_rules/registry.py

@@ -171,15 +171,9 @@ def _currency_rule(msgtype: str) -> Rule:
             )
 
         # Every ``Ccy`` attribute, anywhere in the message.
-        for root in (msg.bah, msg.document):
-            if root is None:
-                continue
-            for el in root.iter():
-                if not isinstance(el.tag, str):
-                    continue
-                code = el.get("Ccy")
-                if code and not is_valid_currency(code):
-                    flag(el, code)
+        for el, code in msg.iter_attr("Ccy"):
+            if code and not is_valid_currency(code):
+                flag(el, code)
         # Standalone ``<Ccy>`` elements (e.g. account currency).
         for el in msg.iter_local("Ccy"):
             code = msg.text_of(el)

{cbpr_usage_rules-0.5.0 → cbpr_usage_rules-0.6.0/src/cbpr_usage_rules.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cbpr-usage-rules
-Version: 0.5.0
+Version: 0.6.0
 Summary: Validate ISO 20022 CBPR+ XML messages against SWIFT usage (business) rules.
 Author: Pete Houghton
 License: MIT License
@@ -282,6 +282,7 @@ matching is by local name, so namespace prefixes never matter.
 cbpr_rules.available(2025)              # -> ['camt.052', 'pacs.008', ...]
 cbpr_rules.list_rules(2025, "pacs.008") # -> [{rule_number, name, description, severity, enforced}, ...]
 cbpr_rules.list_rules(2025, "pacs.008", enforced_only=True)  # only the enforceable rules
+cbpr_rules.list_rules(2025, "pacs.008", with_xpaths=True)    # + "xpaths" each rule affects
 ```
 
 ```bash
@@ -290,6 +291,24 @@ cbpr-validate --year 2025 --type pacs.008 --list               # all rules
 cbpr-validate --year 2025 --type pacs.008 --enforced           # enforceable rules only
 ```
 
+The `--list` / `--enforced` output (and `with_xpaths=True`) annotates each rule with
+the **concrete fields it affects**, so you can see exactly which element/attribute a
+rule constrains — handy when several fields share a name (e.g. many `Ctry` fields, but
+a rule targets only one):
+
+```text
+pacs.008:VAL-IBAN - CBPR_Valid_IBAN
+    //IBAN
+pacs.008:VAL-BIC - CBPR_Valid_Agent_BIC
+    /Document/FIToFICstmrCdtTrf/CdtTrfTxInf/InstgAgt/FinInstnId/BICFI
+pacs.008:R41 - CBPR_Interbank_Settlement_Currency_FormalRule
+    /Document/FIToFICstmrCdtTrf/CdtTrfTxInf/IntrBkSttlmAmt/@Ccy
+```
+
+Paths are derived by running each rule against the bundled example messages
+(best-effort): concrete element paths and `@attribute` targets where present, or a
+`//Name` wildcard for a datatype rule whose element isn't in the examples.
+
 ### Algorithmic field validation
 
 Beyond the published rules, the following formats are validated with their