cbpr-usage-rules 0.1.3__tar.gz → 0.3.0__tar.gz

{cbpr_usage_rules-0.1.3 → cbpr_usage_rules-0.3.0}/CHANGELOG.md

@@ -4,6 +4,24 @@ 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.3.0]
+
+### Added
+- Bundled **example messages**: a minimum and a maximum variant for every
+  supported message type, each pre-verified to pass the usage rules and the
+  CBPR+ XSDs. New API `example_message(year, msgtype, variant="max",
+  wrapper="Envelope")` and `example_variants(year, msgtype)`, and CLI
+  `--example {min,max}` (with `--wrapper TAG`). Data is fictitious/anonymised.
+
+## [0.2.0]
+
+### Added
+- `--format {text,compact,json}` CLI option. The new `compact` format prints one
+  finding per line, compiler/linter-style (`file:line: severity [rule] message | at
+  xpath`) with a stable `VALID:`/`INVALID:` summary line — easy for tools and coding
+  agents to parse. `--json` is now an alias for `--format json`; the default rich
+  text output is unchanged.
+
 ## [0.1.3]
 
 ### Changed

{cbpr_usage_rules-0.1.3 → cbpr_usage_rules-0.3.0}/MANIFEST.in

@@ -2,3 +2,4 @@ include LICENSE
 include README.md
 include CHANGELOG.md
 recursive-include src/cbpr_rules py.typed
+recursive-include src/cbpr_rules/examples *.xml

{cbpr_usage_rules-0.1.3/src/cbpr_usage_rules.egg-info → cbpr_usage_rules-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cbpr-usage-rules
-Version: 0.1.3
+Version: 0.3.0
 Summary: Validate ISO 20022 CBPR+ XML messages against SWIFT usage (business) rules.
 Author: Pete Houghton
 License: MIT License
@@ -112,8 +112,11 @@ result = cbpr_rules.validate_string(xml_text, year=2026)
 # Human-readable (default). Exit code is non-zero if there are violations.
 cbpr-validate payment.xml --year 2025
 
-# JSON output
-cbpr-validate payment.xml --year 2025 --json
+# Compact, one finding per line (compiler-style) — for tools and coding agents
+cbpr-validate payment.xml --year 2025 --format compact
+
+# JSON output (full machine-readable result)
+cbpr-validate payment.xml --year 2025 --json   # same as --format json
 
 # Read from stdin
 cat payment.xml | cbpr-validate --year 2026
@@ -127,10 +130,53 @@ cbpr-validate payment.xml --year 2025 --xsd pacs.008.001.08.xsd
 
 Each reported violation shows the rule, **why** this instance failed (`Problem:`),
 the **offending XML** from your file (`Found:`), and its line + xpath (`At:`).
+
+**For tools and coding agents**, prefer `--format compact` (one finding per line,
+parseable like a compiler/linter) or `--json` (the full structured result):
+
+```text
+$ cbpr-validate payment.xml --year 2025 --format compact
+payment.xml:7: violation [pacs.008:R2] From vs Instructing Agent: ABCDGB2LXXX != GGGGGB2LXXX | at /AppHdr/Fr/FIId/FinInstnId/BICFI
+payment.xml:63: violation [pacs.008:VAL-IBAN] invalid IBAN: 'GB29NWBK60161331926818' | at /Document/.../DbtrAcct/Id/IBAN
+INVALID: 5 violations (87 rules)
+```
+
+Each line is `file:line: severity [rule] message | at xpath`, and the final
+`VALID:` / `INVALID:` line is a stable summary to grep for. With `--xsd`, schema
+errors appear as `schema-error` lines and are counted in the summary.
 Advisory rules are summarised as a count by default; pass `--advisory` to list them.
 
 ---
 
+## Example messages
+
+For every supported message type the package bundles a **minimum** and a
+**maximum** example message — both pre-verified to pass the usage rules *and* the
+CBPR+ XSDs:
+
+- **min** — only the mandatory fields (smallest valid message);
+- **max** — every XSD-visible field populated (one representative occurrence; the
+  richest single legal combination, since some fields are mutually exclusive).
+
+```bash
+# Print to stdout (full AppHdr + Document, wrapped in <Envelope>)
+cbpr-validate --example max --year 2025 --type pacs.008
+cbpr-validate --example min --year 2026 --type pacs.009_cov > template.xml
+
+# Override the wrapper tag (default: Envelope)
+cbpr-validate --example max --year 2025 --type pacs.008 --wrapper BusinessMessage
+```
+```python
+import cbpr_rules
+xml = cbpr_rules.example_message(2025, "pacs.008", "max")   # variant defaults to "max"
+cbpr_rules.example_variants(2025, "pacs.008")               # ['min', 'max']
+```
+
+The data is **fictitious** (synthetic BICs/IBANs/LEIs, `EXAMPLE` names) and does
+not reproduce any real sample — use them as starting templates, not real payments.
+
+---
+
 ## The result object
 
 Both `validate_file` and `validate_string` return a dictionary:

{cbpr_usage_rules-0.1.3 → cbpr_usage_rules-0.3.0}/README.md

@@ -57,8 +57,11 @@ result = cbpr_rules.validate_string(xml_text, year=2026)
 # Human-readable (default). Exit code is non-zero if there are violations.
 cbpr-validate payment.xml --year 2025
 
-# JSON output
-cbpr-validate payment.xml --year 2025 --json
+# Compact, one finding per line (compiler-style) — for tools and coding agents
+cbpr-validate payment.xml --year 2025 --format compact
+
+# JSON output (full machine-readable result)
+cbpr-validate payment.xml --year 2025 --json   # same as --format json
 
 # Read from stdin
 cat payment.xml | cbpr-validate --year 2026
@@ -72,10 +75,53 @@ cbpr-validate payment.xml --year 2025 --xsd pacs.008.001.08.xsd
 
 Each reported violation shows the rule, **why** this instance failed (`Problem:`),
 the **offending XML** from your file (`Found:`), and its line + xpath (`At:`).
+
+**For tools and coding agents**, prefer `--format compact` (one finding per line,
+parseable like a compiler/linter) or `--json` (the full structured result):
+
+```text
+$ cbpr-validate payment.xml --year 2025 --format compact
+payment.xml:7: violation [pacs.008:R2] From vs Instructing Agent: ABCDGB2LXXX != GGGGGB2LXXX | at /AppHdr/Fr/FIId/FinInstnId/BICFI
+payment.xml:63: violation [pacs.008:VAL-IBAN] invalid IBAN: 'GB29NWBK60161331926818' | at /Document/.../DbtrAcct/Id/IBAN
+INVALID: 5 violations (87 rules)
+```
+
+Each line is `file:line: severity [rule] message | at xpath`, and the final
+`VALID:` / `INVALID:` line is a stable summary to grep for. With `--xsd`, schema
+errors appear as `schema-error` lines and are counted in the summary.
 Advisory rules are summarised as a count by default; pass `--advisory` to list them.
 
 ---
 
+## Example messages
+
+For every supported message type the package bundles a **minimum** and a
+**maximum** example message — both pre-verified to pass the usage rules *and* the
+CBPR+ XSDs:
+
+- **min** — only the mandatory fields (smallest valid message);
+- **max** — every XSD-visible field populated (one representative occurrence; the
+  richest single legal combination, since some fields are mutually exclusive).
+
+```bash
+# Print to stdout (full AppHdr + Document, wrapped in <Envelope>)
+cbpr-validate --example max --year 2025 --type pacs.008
+cbpr-validate --example min --year 2026 --type pacs.009_cov > template.xml
+
+# Override the wrapper tag (default: Envelope)
+cbpr-validate --example max --year 2025 --type pacs.008 --wrapper BusinessMessage
+```
+```python
+import cbpr_rules
+xml = cbpr_rules.example_message(2025, "pacs.008", "max")   # variant defaults to "max"
+cbpr_rules.example_variants(2025, "pacs.008")               # ['min', 'max']
+```
+
+The data is **fictitious** (synthetic BICs/IBANs/LEIs, `EXAMPLE` names) and does
+not reproduce any real sample — use them as starting templates, not real payments.
+
+---
+
 ## The result object
 
 Both `validate_file` and `validate_string` return a dictionary:

{cbpr_usage_rules-0.1.3 → cbpr_usage_rules-0.3.0}/pyproject.toml

@@ -50,7 +50,7 @@ version = { attr = "cbpr_rules.__version__" }
 where = ["src"]
 
 [tool.setuptools.package-data]
-cbpr_rules = ["py.typed"]
+cbpr_rules = ["py.typed", "examples/**/*.xml"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{cbpr_usage_rules-0.1.3 → cbpr_usage_rules-0.3.0}/src/cbpr_rules/__init__.py

@@ -4,10 +4,17 @@ This package is AI generated. See the README for details and caveats.
 """
 from __future__ import annotations
 
-__version__ = "0.1.3"
+__version__ = "0.3.0"
 
 from .models import Rule, Severity, Violation
-from .engine import validate_file, validate_string, list_rules, available
+from .engine import (
+    validate_file,
+    validate_string,
+    list_rules,
+    available,
+    example_message,
+    example_variants,
+)
 
 __all__ = [
     "__version__",
@@ -18,4 +25,6 @@ __all__ = [
     "validate_string",
     "list_rules",
     "available",
+    "example_message",
+    "example_variants",
 ]

{cbpr_usage_rules-0.1.3 → cbpr_usage_rules-0.3.0}/src/cbpr_rules/cli.py

@@ -9,7 +9,14 @@ import textwrap
 from typing import List, Optional
 
 from . import __version__
-from .engine import ValidationError, available, list_rules, validate_file, validate_string
+from .engine import (
+    ValidationError,
+    available,
+    example_message,
+    list_rules,
+    validate_file,
+    validate_string,
+)
 
 
 def _build_parser() -> argparse.ArgumentParser:
@@ -26,7 +33,18 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Message type override, e.g. pacs.008 or pacs.008_stp "
         "(auto-detected from the Document namespace if omitted).",
     )
-    p.add_argument("--json", action="store_true", help="Emit JSON instead of text.")
+    p.add_argument(
+        "--format",
+        choices=("text", "compact", "json"),
+        default="text",
+        help="Output format: text (rich, default), compact (one finding per line, "
+        "compiler-style — for tools/agents), or json (full machine-readable).",
+    )
+    p.add_argument(
+        "--json",
+        action="store_true",
+        help="Alias for --format json.",
+    )
     p.add_argument(
         "--xsd",
         action="append",
@@ -40,6 +58,20 @@ def _build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Also list the advisory (non-enforced) rules in full.",
     )
+    p.add_argument(
+        "--example",
+        choices=("min", "max"),
+        help="Print a bundled example message for --year/--type instead of validating: "
+        "min (mandatory fields only) or max (every field populated). Both are XSD- and "
+        "usage-rule-valid.",
+    )
+    p.add_argument(
+        "--wrapper",
+        default="Envelope",
+        metavar="TAG",
+        help="Root element tag wrapping the AppHdr+Document in --example output "
+        "(default: Envelope).",
+    )
     p.add_argument(
         "--list",
         action="store_true",
@@ -125,6 +157,43 @@ def _format_text(result: dict, show_advisory: bool = False) -> str:
     return "\n".join(lines)
 
 
+def _format_compact(result: dict, source: str) -> str:
+    """One finding per line, compiler/linter-style, for tools and coding agents.
+
+    ``<source>:<line>: <severity> [<rule>] <message> | at <xpath>`` per violation,
+    followed by a single greppable ``VALID:``/``INVALID:`` summary line. Advisory
+    (non-enforced) rules are omitted; use --json or text --advisory for those.
+    """
+    lines: List[str] = []
+    for v in result["violations"]:
+        line = v["line"] if v["line"] is not None else "?"
+        message = " ".join((v.get("detail") or v["description"] or "").split())
+        suffix = f" | at {v['xpath']}" if v.get("xpath") else ""
+        lines.append(f"{source}:{line}: {v['severity']} [{v['rule_number']}] {message}{suffix}")
+
+    xsd = result.get("xsd")
+    schema_errors = 0
+    if xsd is not None:
+        for s in xsd["schemas"]:
+            if s.get("load_error"):
+                schema_errors += 1
+                lines.append(f"{s['file']}: schema-error could not load schema: {s['load_error']}")
+            for e in s["errors"]:
+                schema_errors += 1
+                eline = e["line"] if e.get("line") is not None else "?"
+                msg = " ".join((e.get("message") or "").split())
+                lines.append(f"{s['file']}:{eline}: schema-error {msg}")
+
+    n = len(result["violations"])
+    verdict = "VALID" if result["valid"] else "INVALID"
+    parts = [f"{n} violation{'s' if n != 1 else ''}"]
+    if xsd is not None:
+        parts.append(f"{schema_errors} schema error{'s' if schema_errors != 1 else ''}")
+    summary = f"{verdict}: {', '.join(parts)} ({result['rules_evaluated']} rules)"
+    lines.append(summary)
+    return "\n".join(lines)
+
+
 def main(argv: Optional[List[str]] = None) -> int:
     args = _build_parser().parse_args(argv)
 
@@ -136,6 +205,17 @@ def main(argv: Optional[List[str]] = None) -> int:
         print(json.dumps(types) if args.json else "\n".join(types))
         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)
+            return 2
+        try:
+            print(example_message(args.year, args.msgtype, args.example, wrapper=args.wrapper))
+        except ValidationError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        return 0
+
     if args.list:
         if args.year is None or args.msgtype is None:
             print("error: --year and --type are required for --list", file=sys.stderr)
@@ -153,6 +233,7 @@ def main(argv: Optional[List[str]] = None) -> int:
         print("error: --year is required to validate", file=sys.stderr)
         return 2
 
+    source = args.file or "<stdin>"
     try:
         if args.file:
             result = validate_file(args.file, args.year, args.msgtype, xsd=args.xsd)
@@ -163,8 +244,11 @@ def main(argv: Optional[List[str]] = None) -> int:
         print(f"error: {exc}", file=sys.stderr)
         return 2
 
-    if args.json:
+    fmt = "json" if args.json else args.format
+    if fmt == "json":
         print(json.dumps(result, indent=2))
+    elif fmt == "compact":
+        print(_format_compact(result, source))
     else:
         print(_format_text(result, show_advisory=args.advisory))
 

{cbpr_usage_rules-0.1.3 → cbpr_usage_rules-0.3.0}/src/cbpr_rules/engine.py

@@ -1,14 +1,19 @@
 """Validation engine and public API."""
 from __future__ import annotations
 
+from importlib import resources
 from typing import List, Optional
 
+from lxml import etree
+
 from . import loader
 from . import schema as _schema
 from .message import ParsedMessage
 from .models import Rule, Severity
 from .registry import available_message_types, load_rules
 
+_VARIANTS = ("min", "max")
+
 
 class ValidationError(Exception):
     """Raised when a message cannot be validated (parse error, unknown type)."""
@@ -98,3 +103,46 @@ def list_rules(year: int, msgtype: str) -> List[dict]:
 def available(year: int) -> List[str]:
     """Message types with rules available for a given year."""
     return available_message_types(year)
+
+
+def _example_resource(year: int, msgtype: str, variant: str):
+    return (
+        resources.files("cbpr_rules")
+        .joinpath("examples", f"y{int(year)}", f"{msgtype}.{variant}.xml")
+    )
+
+
+def example_variants(year: int, msgtype: str) -> List[str]:
+    """Which example variants ('min'/'max') are bundled for a (year, message type)."""
+    return [v for v in _VARIANTS if _example_resource(year, msgtype, v).is_file()]
+
+
+def example_message(
+    year: int, msgtype: str, variant: str = "max", wrapper: str = "Envelope"
+) -> str:
+    """Return a bundled, pre-verified example message for a (year, message type).
+
+    ``variant`` is 'min' (mandatory fields only) or 'max' (every field populated).
+    Both are guaranteed to pass the usage rules (and the CBPR+ XSDs). ``wrapper``
+    overrides the single root element tag (default ``Envelope``) that holds the
+    ``AppHdr`` and ``Document``. Raises ``ValidationError`` if no such example.
+    """
+    if variant not in _VARIANTS:
+        raise ValidationError(
+            f"Unknown variant '{variant}'; choose one of {', '.join(_VARIANTS)}."
+        )
+    res = _example_resource(year, msgtype, variant)
+    if not res.is_file():
+        types = ", ".join(available(year)) or "(none)"
+        raise ValidationError(
+            f"No {variant} example for '{msgtype}' in {int(year)}. "
+            f"Available message types: {types}."
+        )
+    text = res.read_text(encoding="utf-8")
+    if wrapper and wrapper != "Envelope":
+        root = etree.fromstring(text.encode("utf-8"))
+        root.tag = wrapper
+        text = etree.tostring(
+            root, xml_declaration=True, encoding="UTF-8", pretty_print=True
+        ).decode("utf-8")
+    return text