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

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

@@ -4,6 +4,27 @@ 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
+- Deterministic **ID generation** library (`cbpr_rules.idgen`, "Counting Strings"
+  algorithm — no `random`/`uuid`): `generate_iban`, `generate_lei`, `generate_bic`,
+  `generate_uuid`/`generate_uetr`, `generate_mid`, plus `counting_string`/
+  `counting_sequence` and seeded helpers. Every id is structurally valid and passes
+  the package's own validators; same seed → same output. New CLI
+  `cbpr-validate --generate {iban,lei,bic,uuid,uetr,mid,text}` (with
+  `--seed/--country/--bank/--branch/--count`). The bundled example messages now
+  source their identifiers from this library (seeded per example).
+
 ## [0.4.0]
 
 ### Added

{cbpr_usage_rules-0.4.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.4.0
+Version: 0.6.0
 Summary: Validate ISO 20022 CBPR+ XML messages against SWIFT usage (business) rules.
 Author: Pete Houghton
 License: MIT License
@@ -172,11 +172,34 @@ xml = cbpr_rules.example_message(2025, "pacs.008", "max")   # variant defaults t
 cbpr_rules.example_variants(2025, "pacs.008")               # ['min', 'max']
 ```
 
-The data is **fictitious** (synthetic BICs/IBANs/LEIs, `EXAMPLE` names) and does
+The data is **fictitious** (synthetic, generated BICs/IBANs/LEIs) and does
 not reproduce any real sample — use them as starting templates, not real payments.
 
 ---
 
+## Generating identifiers
+
+The example values above are produced by a small **deterministic** ID generator
+(the "Counting Strings" algorithm — no `random`/`uuid`, same seed → same output).
+Every generated id is structurally valid and passes the tool's own validators.
+
+```bash
+cbpr-validate --generate iban --country AT --seed s1     # ISO 13616 + mod-97
+cbpr-validate --generate lei  --seed acme                # ISO 17442 + check digits
+cbpr-validate --generate bic  --bank JSBP --country GB   # -> JSBPGB..XXX
+cbpr-validate --generate uuid --count 3                  # RFC 4122 v4 (UETR)
+cbpr-validate --generate mid  --country GB               # message identifier
+```
+```python
+from cbpr_rules import generate_iban, generate_lei, generate_bic, generate_uetr
+generate_iban("DE", seed="acme")   # deterministic, valid German IBAN
+generate_bic(country="GB", seed="acme")
+```
+
+IBAN generation supports the 27 EU countries plus GB.
+
+---
+
 ## The result object
 
 Both `validate_file` and `validate_string` return a dictionary:
@@ -259,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
@@ -267,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.4.0 → cbpr_usage_rules-0.6.0}/README.md

@@ -117,11 +117,34 @@ xml = cbpr_rules.example_message(2025, "pacs.008", "max")   # variant defaults t
 cbpr_rules.example_variants(2025, "pacs.008")               # ['min', 'max']
 ```
 
-The data is **fictitious** (synthetic BICs/IBANs/LEIs, `EXAMPLE` names) and does
+The data is **fictitious** (synthetic, generated BICs/IBANs/LEIs) and does
 not reproduce any real sample — use them as starting templates, not real payments.
 
 ---
 
+## Generating identifiers
+
+The example values above are produced by a small **deterministic** ID generator
+(the "Counting Strings" algorithm — no `random`/`uuid`, same seed → same output).
+Every generated id is structurally valid and passes the tool's own validators.
+
+```bash
+cbpr-validate --generate iban --country AT --seed s1     # ISO 13616 + mod-97
+cbpr-validate --generate lei  --seed acme                # ISO 17442 + check digits
+cbpr-validate --generate bic  --bank JSBP --country GB   # -> JSBPGB..XXX
+cbpr-validate --generate uuid --count 3                  # RFC 4122 v4 (UETR)
+cbpr-validate --generate mid  --country GB               # message identifier
+```
+```python
+from cbpr_rules import generate_iban, generate_lei, generate_bic, generate_uetr
+generate_iban("DE", seed="acme")   # deterministic, valid German IBAN
+generate_bic(country="GB", seed="acme")
+```
+
+IBAN generation supports the 27 EU countries plus GB.
+
+---
+
 ## The result object
 
 Both `validate_file` and `validate_string` return a dictionary:
@@ -204,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
@@ -212,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.4.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.4.0"
+__version__ = "0.6.0"
 
 from .models import Rule, Severity, Violation
 from .engine import (
@@ -15,6 +15,16 @@ from .engine import (
     example_message,
     example_variants,
 )
+from .idgen import (
+    generate_iban,
+    generate_lei,
+    generate_bic,
+    generate_uuid,
+    generate_uetr,
+    generate_mid,
+    counting_string,
+    counting_sequence,
+)
 
 __all__ = [
     "__version__",
@@ -27,4 +37,12 @@ __all__ = [
     "available",
     "example_message",
     "example_variants",
+    "generate_iban",
+    "generate_lei",
+    "generate_bic",
+    "generate_uuid",
+    "generate_uetr",
+    "generate_mid",
+    "counting_string",
+    "counting_sequence",
 ]

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

@@ -9,6 +9,7 @@ import textwrap
 from typing import List, Optional
 
 from . import __version__
+from . import idgen
 from .engine import (
     ValidationError,
     available,
@@ -19,6 +20,29 @@ from .engine import (
 )
 
 
+def _generate(args) -> List[str]:
+    """Produce the ``--generate`` output lines (one id per --count)."""
+    kind = args.generate
+    out: List[str] = []
+    for i in range(max(args.count, 1)):
+        seed = f"{args.seed}:{i}" if args.count > 1 else args.seed
+        if kind == "iban":
+            if not args.country:
+                raise ValueError("--generate iban requires --country (e.g. --country AT)")
+            out.append(idgen.generate_iban(args.country, seed))
+        elif kind == "lei":
+            out.append(idgen.generate_lei(seed))
+        elif kind == "bic":
+            out.append(idgen.generate_bic(args.bank, args.country or "GB", args.branch, seed))
+        elif kind in ("uuid", "uetr"):
+            out.append(idgen.generate_uuid(idgen.deterministic_int(seed or str(i), 0, 2**63)))
+        elif kind == "mid":
+            out.append(idgen.generate_mid("CBPR", args.country or "GB", i + 1))
+        elif kind == "text":
+            out.append(idgen.deterministic_string(seed or "text", 16))
+    return out
+
+
 def _build_parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(
         prog="cbpr-validate",
@@ -72,6 +96,17 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Root element tag wrapping the AppHdr+Document in --example output "
         "(default: Envelope).",
     )
+    p.add_argument(
+        "--generate",
+        choices=("iban", "lei", "bic", "uuid", "uetr", "mid", "text"),
+        help="Generate a deterministic, structurally-valid identifier and print it "
+        "(use --seed/--country/--bank/--branch/--count to control output).",
+    )
+    p.add_argument("--seed", default="", help="Seed for --generate (same seed -> same output).")
+    p.add_argument("--country", help="Country code for --generate iban/bic/mid (e.g. AT, GB).")
+    p.add_argument("--bank", help="Bank code for --generate bic (4 letters, padded with X).")
+    p.add_argument("--branch", default="XXX", help="Branch code for --generate bic (default XXX).")
+    p.add_argument("--count", type=int, default=1, help="How many ids to generate (default 1).")
     p.add_argument(
         "--list",
         action="store_true",
@@ -211,6 +246,15 @@ def main(argv: Optional[List[str]] = None) -> int:
         print(json.dumps(types) if args.json else "\n".join(types))
         return 0
 
+    if args.generate:
+        try:
+            for line in _generate(args):
+                print(line)
+        except (ValueError, ValidationError) as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        return 0
+
     if args.example:
         if args.year is None or args.msgtype is None:
             print("error: --example requires --year and --type", file=sys.stderr)
@@ -226,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.4.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