brkraw 0.3.11__py3-none-any.whl → 0.5.0__py3-none-any.whl

brkraw/specs/remapper/validator.py

@@ -0,0 +1,314 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, IO, List, Dict, Union, Optional
+from importlib import resources
+
+try:
+    resources.files  # type: ignore[attr-defined]
+except AttributeError:  # pragma: no cover - fallback for Python 3.8
+    import importlib_resources as resources  # type: ignore[assignment]
+
+import yaml
+
+from ..meta import validate_meta
+
+_ALLOWED_FILES = {"method", "acqp", "visu_pars", "reco", "subject"}
+_RULE_KEYS = {"sources", "inputs", "const", "ref", "transform", "default"}
+_INPUT_KEYS = {"sources", "const", "ref", "transform", "default", "required"}
+_INLINE_SOURCE_KEYS = {"inputs", "transform"}
+_META_KEY = "__meta__"
+
+
+def _validate_transforms_source(
+    transforms_source: Optional[Union[str, Path, List[str], List[Path], IO[str], IO[bytes]]],
+    errors: List[str],
+) -> None:
+    if transforms_source is None:
+        return
+    if isinstance(transforms_source, (str, Path)):
+        src_path = Path(transforms_source)
+        if not src_path.exists():
+            errors.append(f"transforms_source: not found: {src_path}")
+        return
+    if isinstance(transforms_source, list):
+        for item in transforms_source:
+            if not isinstance(item, (str, Path)):
+                errors.append("transforms_source: list entries must be paths.")
+                continue
+            src_path = Path(item)
+            if not src_path.exists():
+                errors.append(f"transforms_source: not found: {src_path}")
+
+
+def _load_schema() -> Dict[str, Any]:
+    if __package__ is None:
+        raise RuntimeError("Package context required to load remapper schema.")
+    with resources.files("brkraw.schema").joinpath("remapper.yaml").open(
+        "r", encoding="utf-8"
+    ) as handle:
+        return yaml.safe_load(handle)
+
+
+def _load_map_schema() -> Dict[str, Any]:
+    if __package__ is None:
+        raise RuntimeError("Package context required to load map schema.")
+    with resources.files("brkraw.schema").joinpath("context_map.yaml").open(
+        "r", encoding="utf-8"
+    ) as handle:
+        return yaml.safe_load(handle)
+
+
+def _validate_sources(sources: Any, path: str, errors: List[str]) -> None:
+    if not isinstance(sources, list):
+        errors.append(f"{path}: sources must be a list.")
+        return
+    for idx, src in enumerate(sources):
+        item_path = f"{path}.sources[{idx}]"
+        if not isinstance(src, dict):
+            errors.append(f"{item_path}: source must be an object.")
+            continue
+        if "inputs" in src:
+            extra = set(src.keys()) - _INLINE_SOURCE_KEYS
+            if extra:
+                errors.append(f"{item_path}: unexpected keys {sorted(extra)}.")
+            _validate_inputs(src["inputs"], item_path, errors)
+            if "transform" in src:
+                t = src["transform"]
+                if isinstance(t, list):
+                    if not all(isinstance(name, str) for name in t):
+                        errors.append(f"{item_path}: transform list must be strings.")
+                elif not isinstance(t, str):
+                    errors.append(f"{item_path}: transform must be a string or list.")
+            continue
+        extra = set(src.keys()) - {"file", "key", "reco_id"}
+        if extra:
+            errors.append(f"{item_path}: unexpected keys {sorted(extra)}.")
+        if "file" not in src or "key" not in src:
+            errors.append(f"{item_path}: requires file and key.")
+            continue
+        if src["file"] not in _ALLOWED_FILES:
+            errors.append(f"{item_path}: invalid file {src['file']!r}.")
+        if not isinstance(src["key"], str):
+            errors.append(f"{item_path}: key must be a string.")
+        reco_id = src.get("reco_id")
+        if reco_id is not None and (not isinstance(reco_id, int) or reco_id < 1):
+            errors.append(f"{item_path}: reco_id must be int >= 1.")
+
+
+def _validate_inputs(inputs: Any, path: str, errors: List[str]) -> None:
+    if not isinstance(inputs, dict):
+        errors.append(f"{path}: inputs must be a mapping.")
+        return
+    for name, spec in inputs.items():
+        item_path = f"{path}.inputs[{name!r}]"
+        if isinstance(spec, str):
+            if not spec.startswith("$"):
+                errors.append(f"{item_path}: input shorthand must start with '$'.")
+            continue
+        if not isinstance(spec, dict):
+            errors.append(f"{item_path}: input spec must be an object.")
+            continue
+        extra = set(spec.keys()) - _INPUT_KEYS
+        if extra:
+            errors.append(f"{item_path}: unexpected keys {sorted(extra)}.")
+        if not any(k in spec for k in ("sources", "const", "ref")):
+            errors.append(f"{item_path}: requires sources, const, or ref.")
+        if "sources" in spec:
+            _validate_sources(spec["sources"], item_path, errors)
+        if "ref" in spec and not isinstance(spec["ref"], str):
+            errors.append(f"{item_path}: ref must be a string.")
+        if "transform" in spec:
+            t = spec["transform"]
+            if isinstance(t, list):
+                if not all(isinstance(name, str) for name in t):
+                    errors.append(f"{item_path}: transform list must be strings.")
+            elif not isinstance(t, str):
+                errors.append(f"{item_path}: transform must be a string or list.")
+        if "required" in spec and not isinstance(spec["required"], bool):
+            errors.append(f"{item_path}: required must be a boolean.")
+
+
+def _validate_spec_minimal(spec: Any) -> List[str]:
+    errors: List[str] = []
+    if not isinstance(spec, dict):
+        errors.append("spec: must be a mapping.")
+        return errors
+    if _META_KEY not in spec:
+        errors.append("spec.__meta__: is required.")
+    else:
+        errors.extend(
+            validate_meta(
+                spec.get(_META_KEY),
+                allow_extra_keys={"include", "include_mode", "transforms_source", "__spec_path__"},
+                raise_on_error=False,
+            )
+        )
+    for key, rule in spec.items():
+        if key == _META_KEY:
+            continue
+        path = f"spec[{key!r}]"
+        if not isinstance(rule, dict):
+            errors.append(f"{path}: rule must be an object.")
+            continue
+        extra = set(rule.keys()) - _RULE_KEYS
+        if extra:
+            errors.append(f"{path}: unexpected keys {sorted(extra)}.")
+        if not any(k in rule for k in ("sources", "inputs", "const", "ref")):
+            errors.append(f"{path}: requires sources, inputs, const, or ref.")
+        if "sources" in rule:
+            _validate_sources(rule["sources"], path, errors)
+        if "inputs" in rule:
+            _validate_inputs(rule["inputs"], path, errors)
+        if "ref" in rule and not isinstance(rule["ref"], str):
+            errors.append(f"{path}: ref must be a string.")
+        if "transform" in rule:
+            t = rule["transform"]
+            if isinstance(t, list):
+                if not all(isinstance(name, str) for name in t):
+                    errors.append(f"{path}: transform list must be strings.")
+            elif not isinstance(t, str):
+                errors.append(f"{path}: transform must be a string or list.")
+    return errors
+
+
+def validate_spec(
+    spec: Any,
+    *,
+    transforms_source: Optional[Union[str, Path, List[str], List[Path], IO[str], IO[bytes]]] = None,
+    raise_on_error: bool = True,
+) -> List[str]:
+    """Validate a remapper spec against the schema.
+
+    Args:
+        spec: Parsed spec mapping to validate.
+        raise_on_error: If True, raise ValueError on validation errors.
+
+    Returns:
+        List of validation error messages (empty when valid).
+    """
+    errors: List[str] = []
+    try:
+        import jsonschema
+    except Exception:
+        errors = _validate_spec_minimal(spec)
+    else:
+        schema = _load_schema()
+        validator = jsonschema.Draft202012Validator(schema)
+        for err in validator.iter_errors(spec):
+            path = ".".join(str(p) for p in err.path)
+            prefix = f"spec.{path}" if path else "spec"
+            errors.append(f"{prefix}: {err.message}")
+
+    meta = spec.get(_META_KEY) if isinstance(spec, dict) else None
+    errors.extend(
+        validate_meta(
+            meta,
+            allow_extra_keys={"include", "include_mode", "transforms_source", "__spec_path__"},
+            raise_on_error=False,
+        )
+    )
+    _validate_transforms_source(transforms_source, errors)
+    if errors and raise_on_error:
+        raise ValueError("Invalid remapper spec:\n" + "\n".join(errors))
+    return errors
+
+
+def _validate_map_minimal(map_data: Any) -> List[str]:
+    errors: List[str] = []
+    if not isinstance(map_data, dict):
+        errors.append("map: must be a mapping.")
+        return errors
+    for key, value in map_data.items():
+        if key == "__meta__":
+            continue
+        if not isinstance(key, str):
+            errors.append(f"map[{key!r}]: key must be a string.")
+        if isinstance(value, list):
+            for idx, rule in enumerate(value):
+                _validate_map_rule(rule, key, errors, idx=idx)
+        else:
+            _validate_map_rule(value, key, errors, idx=None)
+    return errors
+
+
+def _validate_map_rule(
+    rule: Any,
+    key: str,
+    errors: List[str],
+    *,
+    idx: Optional[Union[int, str]],
+) -> None:
+    label = f"map[{key!r}]" if idx is None else f"map[{key!r}][{idx}]"
+    if not isinstance(rule, dict):
+        errors.append(f"{label}: rule must be a mapping.")
+        return
+    cases = rule.get("cases")
+    if cases is not None:
+        if not isinstance(cases, list):
+            errors.append(f"{label}: cases must be a list.")
+        else:
+            for case_idx, case in enumerate(cases):
+                nested = f"{idx}.cases[{case_idx}]" if idx is not None else f"cases[{case_idx}]"
+                _validate_map_rule(case, key, errors, idx=nested)
+    rule_type = rule.get("type")
+    if rule_type is None:
+        if "values" in rule:
+            rule_type = "mapping"
+        elif "value" in rule:
+            rule_type = "const"
+    if rule_type not in {"mapping", "const", None}:
+        errors.append(f"{label}: invalid type {rule_type!r}.")
+    if rule_type == "mapping":
+        table = rule.get("values")
+        if not isinstance(table, dict) and cases is None:
+            errors.append(f"{label}: values must be a mapping.")
+    when = rule.get("when")
+    if when is not None and not isinstance(when, dict):
+        errors.append(f"{label}: when must be a mapping.")
+    override = rule.get("override")
+    if override is not None and not isinstance(override, bool):
+        errors.append(f"{label}: override must be a boolean.")
+
+
+def validate_map_data(map_data: Any, *, raise_on_error: bool = True) -> List[str]:
+    """Validate a map file mapping.
+
+    Args:
+        map_data: Parsed map mapping to validate.
+        raise_on_error: If True, raise ValueError on validation errors.
+
+    Returns:
+        List of validation error messages (empty when valid).
+    """
+    errors: List[str] = []
+    try:
+        import jsonschema
+    except Exception:
+        errors = _validate_map_minimal(map_data)
+    else:
+        schema = _load_map_schema()
+        validator = jsonschema.Draft202012Validator(schema)
+        for err in validator.iter_errors(map_data):
+            path = ".".join(str(p) for p in err.path)
+            prefix = f"map.{path}" if path else "map"
+            errors.append(f"{prefix}: {err.message}")
+        errors.extend(_validate_map_minimal(map_data))
+    if errors and raise_on_error:
+        raise ValueError("Invalid map file:\n" + "\n".join(errors))
+    return errors
+
+
+def validate_context_map(path: Union[str, Path], *, raise_on_error: bool = True) -> List[str]:
+    """Load and validate a context map from YAML.
+
+    Args:
+        path: Context map YAML file path.
+        raise_on_error: If True, raise ValueError on validation errors.
+
+    Returns:
+        List of validation error messages (empty when valid).
+    """
+    map_path = Path(path)
+    data = yaml.safe_load(map_path.read_text(encoding="utf-8"))
+    return validate_map_data(data, raise_on_error=raise_on_error)

brkraw/specs/rules/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .logic import load_rules, rule_matches, select_rule_use
+from .validator import validate_rules
+
+__all__ = ["load_rules", "rule_matches", "select_rule_use", "validate_rules"]

brkraw/specs/rules/logic.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, List, Dict, Optional, Union
+
+import yaml
+
+from ...core import config as config_module
+from ..remapper import load_spec, map_parameters
+from .validator import validate_rules
+import logging
+
+logger = logging.getLogger("brkraw")
+
+RULE_CATEGORIES = ("info_spec", "metadata_spec", "converter_hook")
+SPEC_CATEGORIES = ("info_spec", "metadata_spec")
+
+
+def _iter_rule_files(rules_dir: Path) -> List[Path]:
+    if not rules_dir.exists():
+        return []
+    files = list(rules_dir.rglob("*.yaml")) + list(rules_dir.rglob("*.yml"))
+    return sorted({p.resolve() for p in files})
+
+
+def _load_rule_file(path: Path) -> Dict[str, Any]:
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ValueError(f"Rule file must be a mapping: {path}")
+    return data
+
+
+def _resolve_spec_path(use: str, base: Path) -> Path:
+    candidate = Path(use)
+    if candidate.is_absolute():
+        return candidate
+    if candidate.parts and candidate.parts[0] == "specs":
+        return base / candidate
+    return base / "specs" / candidate
+
+
+def _resolve_rule_use(rule: Dict[str, Any], *, base: Path) -> Optional[Path]:
+    use = rule.get("use")
+    if not isinstance(use, str):
+        return None
+    version = rule.get("version") if isinstance(rule.get("version"), str) else None
+    category = rule.get("__category__") if isinstance(rule.get("__category__"), str) else None
+    try:
+        from ...apps.addon.core import resolve_spec_reference
+    except Exception:
+        resolve_spec_reference = None
+    if resolve_spec_reference is None:
+        return _resolve_spec_path(use, base)
+    return resolve_spec_reference(use, category=category, version=version, root=base)
+
+
+def _resolve_operand(value: Any, bindings: Dict[str, Any]) -> Any:
+    if isinstance(value, str) and value.startswith("$"):
+        return bindings.get(value[1:])
+    return value
+
+
+def _eval_expr(expr: Any, bindings: Dict[str, Any]) -> bool:
+    if expr is None:
+        return True
+    if not isinstance(expr, dict):
+        raise ValueError(f"Rule if must be a mapping, got {type(expr)!r}")
+    if len(expr) != 1:
+        raise ValueError("Rule if must contain a single operator.")
+    op, args = next(iter(expr.items()))
+    if op == "any":
+        return any(_eval_expr(item, bindings) for item in args)
+    if op == "all":
+        return all(_eval_expr(item, bindings) for item in args)
+    if op == "not":
+        return not _eval_expr(args, bindings)
+    if op == "always":
+        if not isinstance(args, bool):
+            raise ValueError("always expects a boolean.")
+        return args
+
+    if not isinstance(args, (list, tuple)) or len(args) != 2:
+        raise ValueError(f"Operator {op!r} requires two arguments.")
+    left = _resolve_operand(args[0], bindings)
+    right = _resolve_operand(args[1], bindings)
+
+    if left is None or right is None:
+        if op == "eq":
+            return left == right
+        if op == "ne":
+            return left != right
+        return False
+
+    if op == "eq":
+        return left == right
+    if op == "ne":
+        return left != right
+    if op == "in":
+        try:
+            return left in right
+        except TypeError:
+            return False
+    if op == "regex":
+        import re
+        if left is None:
+            return False
+        return re.search(str(right), str(left)) is not None
+    if op == "startswith":
+        if left is None:
+            return False
+        return str(left).startswith(str(right))
+    if op == "contains":
+        if left is None:
+            return False
+        if isinstance(left, (list, tuple, set)):
+            return right in left
+        return str(right) in str(left)
+    if op == "gt":
+        return left > right
+    if op == "ge":
+        return left >= right
+    if op == "lt":
+        return left < right
+    if op == "le":
+        return left <= right
+    raise ValueError(f"Unsupported operator: {op}")
+
+
+def _load_rule_transforms(rule: Dict[str, Any], base: Path) -> Dict[str, Any]:
+    transforms = rule.get("__transforms__")
+    if isinstance(transforms, dict):
+        return transforms
+    category = rule.get("__category__") if isinstance(rule.get("__category__"), str) else None
+    if category and category not in SPEC_CATEGORIES:
+        return {}
+    use = rule.get("use")
+    if not isinstance(use, str):
+        return {}
+    spec_path = rule.get("__spec_path__")
+    if isinstance(spec_path, Path):
+        _, transforms = load_spec(spec_path, validate=False)
+        return transforms
+    spec_path = _resolve_rule_use(rule, base=base)
+    if isinstance(spec_path, Path) and spec_path.exists():
+        _, transforms = load_spec(spec_path, validate=False)
+        return transforms
+    return {}
+
+
+def rule_matches(
+    source: Any,
+    rule: Dict[str, Any],
+    *,
+    base: Path,
+) -> bool:
+    when = rule.get("when")
+    if when is None:
+        logger.debug("Rule %r: no 'when' clause, matches by default.", rule.get("name"))
+        return True
+    if not isinstance(when, dict):
+        raise ValueError("Rule 'when' must be a mapping.")
+    transforms = _load_rule_transforms(rule, base)
+    bindings = map_parameters(source, when, transforms, validate=False)
+    logger.debug("Rule %r: when bindings=%s", rule.get("name"), bindings)
+    try:
+        matched = _eval_expr(rule.get("if"), bindings)
+        logger.debug(
+            "Rule %r: bindings=%s if=%s matched=%s",
+            rule.get("name"),
+            bindings,
+            rule.get("if"),
+            matched,
+        )
+        return matched
+    except Exception as exc:
+        name = rule.get("name", "<unnamed>")
+        raise ValueError(f"Rule {name!r} evaluation failed: {exc}") from exc
+
+
+def select_rule_use(
+    source: Any,
+    rules: List[Dict[str, Any]],
+    *,
+    base: Path,
+    resolve_paths: bool = True,
+) -> Optional[Union[str, Path]]:
+    selected: Optional[Union[str, Path]] = None
+    for rule in rules:
+        if not isinstance(rule, dict):
+            continue
+        logger.debug("Evaluating rule %r (use=%r).", rule.get("name"), rule.get("use"))
+        try:
+            matched = rule_matches(source, rule, base=base)
+        except Exception as exc:
+            logger.debug(
+                "Rule %r evaluation failed: %s",
+                rule.get("name"),
+                exc,
+                exc_info=True,
+            )
+            continue
+        logger.debug("Rule %r: match=%s", rule.get("name"), matched)
+        if matched:
+            use = rule.get("use")
+            if isinstance(use, str):
+                if not resolve_paths:
+                    selected = use
+                else:
+                    spec_path = rule.get("__spec_path__")
+                    if isinstance(spec_path, Path):
+                        selected = spec_path
+                    else:
+                        selected = _resolve_spec_path(use, base)
+                logger.debug("Rule %r matched, selected use=%r.", rule.get("name"), selected)
+            else:
+                logger.debug("Rule %r matched but has no usable 'use' entry.", rule.get("name"))
+        else:
+            logger.debug("Rule %r did not match.", rule.get("name"))
+    logger.debug("Rule selection result: %r", selected)
+    return selected
+
+
+def load_rules(
+    root: Optional[Union[str, Path]] = None,
+    *,
+    rules_dir: Optional[Path] = None,
+    validate: bool = True,
+) -> Dict[str, List[Dict[str, Any]]]:
+    base = config_module.resolve_root(root)
+    rules_path = rules_dir or (base / "rules")
+    merged = {key: [] for key in RULE_CATEGORIES}
+    transforms_cache: Dict[Path, Dict[str, Any]] = {}
+    for path in _iter_rule_files(rules_path):
+        data = _load_rule_file(path)
+        if validate and data:
+            validate_rules(data)
+        for key in RULE_CATEGORIES:
+            items = data.get(key, [])
+            if items:
+                if not isinstance(items, list):
+                    raise ValueError(f"{path}: {key} must be a list.")
+                for item in items:
+                    if not isinstance(item, dict):
+                        continue
+                    item["__category__"] = key
+                    if key in SPEC_CATEGORIES:
+                        use = item.get("use")
+                        if not isinstance(use, str):
+                            continue
+                        spec_path = _resolve_rule_use(item, base=base)
+                        if not isinstance(spec_path, Path) or not spec_path.exists():
+                            if validate:
+                                raise FileNotFoundError(spec_path)
+                            continue
+                        if spec_path not in transforms_cache:
+                            _, transforms = load_spec(spec_path, validate=validate)
+                            transforms_cache[spec_path] = transforms
+                        item["__spec_path__"] = spec_path
+                        item["__transforms__"] = transforms_cache[spec_path]
+                merged[key].extend(items)
+    return merged

brkraw/specs/rules/validator.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, List, Dict, Optional
+from importlib import resources
+
+try:
+    resources.files  # type: ignore[attr-defined]
+except AttributeError:  # pragma: no cover - fallback for Python 3.8
+    import importlib_resources as resources  # type: ignore[assignment]
+
+import yaml
+
+from ...core.entrypoints import list_entry_points
+
+CONVERTER_GROUP = "brkraw.converter_hook"
+
+def _load_schema() -> Dict[str, Any]:
+    if __package__ is None:
+        raise RuntimeError("Package context required to load rules schema.")
+    with resources.files("brkraw.schema").joinpath("rules.yaml").open(
+        "r", encoding="utf-8"
+    ) as handle:
+        return yaml.safe_load(handle)
+
+
+def validate_rules(
+    rule_data: Dict[str, Any],
+    schema_path: Optional[Path] = None,
+) -> None:
+    """Validate rule mappings against schema and hook availability.
+
+    Args:
+        rule_data: Parsed rule mapping to validate.
+        schema_path: Optional rules schema path override.
+    """
+    try:
+        import jsonschema
+    except ImportError as exc:
+        raise RuntimeError("jsonschema is required to validate rule files.") from exc
+    schema = (
+        _load_schema()
+        if schema_path is None
+        else yaml.safe_load(schema_path.read_text(encoding="utf-8"))
+    )
+    jsonschema.Draft202012Validator(schema).validate(rule_data)
+    _validate_default_rules(rule_data)
+    _validate_converter_hooks(rule_data)
+
+
+def _validate_default_rules(rule_data: Dict[str, Any]) -> None:
+    """Ensure default rules (no 'when') appear first and avoid 'if'."""
+    for category, items in rule_data.items():
+        if not isinstance(items, list):
+            continue
+        default_indexes = []
+        for idx, rule in enumerate(items):
+            if not isinstance(rule, dict):
+                continue
+            has_when = "when" in rule
+            has_if = "if" in rule
+            if has_when and not has_if:
+                name = rule.get("name", "<unnamed>")
+                raise ValueError(
+                    f"Rule {name!r} in {category!r} must define 'if' when 'when' is present."
+                )
+            if not has_when:
+                if has_if:
+                    name = rule.get("name", "<unnamed>")
+                    raise ValueError(
+                        f"Rule {name!r} in {category!r} cannot use 'if' without 'when'."
+                    )
+                default_indexes.append(idx)
+        if not default_indexes:
+            continue
+        if len(default_indexes) > 1 or default_indexes[0] != 0:
+            raise ValueError(
+                f"Default rule (no 'when') must be the first entry in {category!r}."
+            )
+
+
+def _validate_converter_hooks(rule_data: Dict[str, Any]) -> None:
+    """Ensure converter_hook references resolve to installed hooks."""
+    missing: List[str] = []
+    items = rule_data.get("converter_hook", [])
+    if not items:
+        return
+    if not isinstance(items, list):
+        return
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        use = item.get("use")
+        if not isinstance(use, str):
+            continue
+        if not list_entry_points(CONVERTER_GROUP, use):
+            missing.append(use)
+    if missing:
+        missing_text = ", ".join(sorted(set(missing)))
+        raise ValueError(
+            "converter_hook references missing hooks: "
+            f"{missing_text} (group={CONVERTER_GROUP})"
+        )