wxcli 1.2.0__py3-none-any.whl

wxcli/migration/transform/pattern_converter.py

@@ -0,0 +1,106 @@
+"""Pattern converter: CUCM route pattern -> Webex dial plan pattern.
+
+Converts CUCM dial pattern syntax to Webex-compatible E.164 format patterns.
+Used by routing_mapper and css_mapper for pattern syntax conversion.
+
+(from 03b-transform-mappers.md §6, Pattern Syntax Conversion table)
+(from 03b-transform-mappers.md §13, Pattern Converter shared utility)
+
+Conversion rules:
+    - Strip access code prefix (everything before '.')
+    - Prepend country code prefix (e.g., "+1") to the remaining pattern
+    - Preserve wildcards: X, !, [ranges]
+    - Strip '.' separator entirely
+    - International access code (e.g., "011") is stripped when followed by wildcard
+    - '@' macro requires expansion (not handled here — see migration config)
+"""
+
+from __future__ import annotations
+
+
+def cucm_to_webex_pattern(
+    cucm_pattern: str,
+    country_code: str = "+1",
+    outside_dial_digit: str = "9",
+) -> str:
+    """Convert a CUCM route pattern to a Webex dial plan pattern.
+
+    (from 03b-transform-mappers.md §13: Pattern Converter)
+
+    Args:
+        cucm_pattern: CUCM route pattern (e.g., "9.1[2-9]XXXXXXXXX", "9.011!")
+        country_code: E.164 country prefix including '+' (e.g., "+1", "+44")
+        outside_dial_digit: The CUCM outside access digit (e.g., "9")
+
+    Returns:
+        Webex-format dial plan pattern (e.g., "+1[2-9]XXXXXXXXX", "+!")
+
+    Examples:
+        >>> cucm_to_webex_pattern("9.1[2-9]XXXXXXXXX", "+1", "9")
+        '+1[2-9]XXXXXXXXX'
+        >>> cucm_to_webex_pattern("9.011!", "+1", "9")
+        '+!'
+        >>> cucm_to_webex_pattern("1XXX", "+1", "9")
+        '+11XXX'
+        >>> cucm_to_webex_pattern("\\\\+1XXXXXXXXXX", "+1", "9")
+        '+1XXXXXXXXXX'
+    """
+    if not cucm_pattern:
+        return cucm_pattern
+
+    # Coerce outside_dial_digit to str (config may supply it as int, e.g. 9)
+    outside_dial_digit = str(outside_dial_digit)
+
+    # Strip leading backslash-escaped '+' (CUCM uses \+ for literal plus)
+    # (CUCM route patterns sometimes escape + as \\+)
+    working = cucm_pattern.replace("\\+", "+")
+
+    # If pattern already starts with '+', it's already E.164 format
+    if working.startswith("+"):
+        return working
+
+    # Track whether we stripped an access code. When an access code is present,
+    # the remainder typically starts with the national prefix (e.g., "1" for US).
+    # Without an access code, the pattern is a direct route pattern where digits
+    # should NOT be interpreted as embedded country codes.
+    access_code_stripped = False
+
+    # Strip access code prefix: everything before '.' (the dot separator)
+    # (from 03b-transform-mappers.md §6: "Strips access code prefix (before '.')")
+    if "." in working:
+        _prefix, remainder = working.split(".", 1)
+        working = remainder
+        access_code_stripped = True
+    # If no dot but starts with outside_dial_digit followed by known patterns,
+    # strip the leading access code
+    elif working.startswith(outside_dial_digit) and len(working) > 1:
+        next_char = working[len(outside_dial_digit):]
+        if next_char and (next_char[0].isdigit() or next_char[0] in "X[!"):
+            working = working[len(outside_dial_digit):]
+            access_code_stripped = True
+
+    # Handle international access code patterns (e.g., "011!")
+    # (from 03b-transform-mappers.md §6: "9.011!" -> "+!")
+    # Common international access codes: 011 (US/CA), 00 (many countries)
+    intl_prefixes = ["011", "00"]
+    for intl in intl_prefixes:
+        if working.startswith(intl):
+            remainder_after_intl = working[len(intl):]
+            if remainder_after_intl:
+                return f"+{remainder_after_intl}"
+            else:
+                return f"+{working}"
+
+    # If we stripped an access code, the remainder starts with the national
+    # prefix digits (e.g., "1" for "+1"). Just prepend "+".
+    # (from 03b-transform-mappers.md §6: "Strip access code prefix, prepend + and country code")
+    # Example: "9.1[2-9]XXXXXXXXX" -> strip "9." -> "1[2-9]XXXXXXXXX" -> "+1[2-9]XXXXXXXXX"
+    if access_code_stripped:
+        bare_cc = country_code.lstrip("+")
+        if bare_cc and working.startswith(bare_cc):
+            return f"+{working}"
+
+    # Prepend full country code prefix for patterns without embedded national prefix
+    # (from 03b-transform-mappers.md §6: "prepend + and country code")
+    # country_code already includes '+' (e.g., "+1")
+    return f"{country_code}{working}"

wxcli/migration/transform/pipeline.py

@@ -0,0 +1,271 @@
+"""Normalization pipeline: DiscoveryResult → normalized store → cross-references.
+
+This is the Phase 04 entry point. It connects Phase 03 extraction output
+(DiscoveryResult.raw_data) to the normalizers and CrossReferenceBuilder.
+
+Pipeline steps:
+1. Iterate raw_data using RAW_DATA_MAPPING to call the right normalizer per item
+2. Classify common-area phones as workspaces (post-normalization)
+3. Normalize Unity Connection per-user VM settings (if present)
+4. Upsert all normalized objects to the MigrationStore
+5. Run CrossReferenceBuilder (pass 2)
+
+(from 02-normalization-architecture.md, two-pass ELT design)
+(from Phase 03 DiscoveryResult.raw_data contract)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from datetime import datetime, timezone
+
+from wxcli.migration.models import MigrationObject, MigrationStatus, Provenance
+from wxcli.migration.store import MigrationStore
+from wxcli.migration.transform.cross_reference import CrossReferenceBuilder
+from wxcli.migration.transform.normalizers import (
+    NORMALIZER_REGISTRY,
+    RAW_DATA_MAPPING,
+    is_common_area_device,
+    normalize_dect_group,
+    normalize_unity_vm_settings,
+    normalize_workspace,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def normalize_discovery(
+    raw_data: dict[str, dict[str, Any]],
+    store: MigrationStore,
+    cluster: str = "default",
+    default_country_code: str = "US",
+    site_prefix_rules: list[dict] | None = None,
+    dect_inventory: list[dict[str, str]] | None = None,
+) -> dict[str, Any]:
+    """Run the full normalization pipeline on discovery raw_data.
+
+    Args:
+        raw_data: DiscoveryResult.raw_data from Phase 03 extraction.
+        store: MigrationStore to write normalized objects to.
+        cluster: CUCM cluster name for provenance.
+        default_country_code: ISO country code for E.164 normalization.
+        site_prefix_rules: Prefix stripping rules for E.164 normalization.
+        dect_inventory: Optional list of base station dicts from --dect-inventory
+            CSV. Each dict has keys: coverage_zone, base_station_mac,
+            base_station_model.  Passed through to normalize_dect_group() so
+            that inventory data is merged into CanonicalDECTNetwork objects.
+
+    Returns:
+        Summary dict with counts per step.
+    """
+    summary: dict[str, Any] = {"pass1": {}, "pass2": {}}
+
+    # ------------------------------------------------------------------
+    # Pass 1: Normalize all objects from raw_data
+    # ------------------------------------------------------------------
+
+    total_normalized = 0
+
+    for extractor_key, sub_key, normalizer_key in RAW_DATA_MAPPING:
+        normalizer_fn = NORMALIZER_REGISTRY.get(normalizer_key)
+        if normalizer_fn is None:
+            logger.warning("No normalizer for %s/%s (key: %s)", extractor_key, sub_key, normalizer_key)
+            continue
+
+        extractor_data = raw_data.get(extractor_key, {})
+        items = extractor_data.get(sub_key, [])
+        if not isinstance(items, list):
+            continue
+
+        count = 0
+        for item in items:
+            try:
+                obj = normalizer_fn(item, cluster=cluster)
+                if obj is None:
+                    continue  # Normalizer rejected this item (e.g., empty name)
+                store.upsert_object(obj)
+                count += 1
+            except Exception:
+                logger.exception(
+                    "Failed to normalize %s/%s item: %s",
+                    extractor_key, sub_key,
+                    item.get("name", item.get("pattern", item.get("pkid", "?"))),
+                )
+
+        summary["pass1"][f"{extractor_key}/{sub_key}"] = count
+        total_normalized += count
+        if count > 0:
+            logger.info("Normalized %d %s/%s objects", count, extractor_key, sub_key)
+
+    # ------------------------------------------------------------------
+    # Preserve raw phone objects for mappers (§8 fix)
+    # normalize_phone() creates CanonicalDevice (object_type="device") but
+    # MonitoringMapper, CallForwardingMapper, DeviceLayoutMapper, DeviceMapper,
+    # and WorkspaceMapper all call store.get_objects("phone") expecting raw
+    # phone dicts with speeddials, busyLampFields, and per-line call forwarding.
+    # Store raw phone data as MigrationObject with canonical_id="phone:{name}".
+    # ------------------------------------------------------------------
+
+    phones = raw_data.get("devices", {}).get("phones", [])
+    raw_phone_count = 0
+    for phone in phones:
+        phone_name = phone.get("name", "")
+        if not phone_name:
+            continue
+        raw_obj = MigrationObject(
+            canonical_id=f"phone:{phone_name}",
+            provenance=Provenance(
+                source_system="cucm",
+                source_id=phone.get("pkid", ""),
+                source_name=phone_name,
+                cluster=cluster,
+                extracted_at=datetime.now(timezone.utc),
+            ),
+            status=MigrationStatus.NORMALIZED,
+            pre_migration_state=phone,
+        )
+        store.upsert_object(raw_obj)
+        raw_phone_count += 1
+
+    summary["pass1"]["raw_phones_preserved"] = raw_phone_count
+    if raw_phone_count > 0:
+        logger.info("Preserved %d raw phone objects for mappers", raw_phone_count)
+
+    # ------------------------------------------------------------------
+    # Post-normalization: classify common-area phones as workspaces
+    # (from 02b §2.8: common-area phones have ownerUserName=None, class=Phone)
+    # Skip phones whose description matches a known user — those are
+    # user-owned phones that just lack an explicit ownerUserName in CUCM.
+    # A user can own multiple phones; the cross-ref builder handles this.
+    # ------------------------------------------------------------------
+
+    # Build a simple user lookup for description matching
+    _user_names: dict[str, str] = {}  # lowercase key → user canonical_id
+    for u in store.get_objects("user"):
+        uid = (u.get("cucm_userid") or "").lower()
+        fn = (u.get("first_name") or "").lower().strip()
+        ln = (u.get("last_name") or "").lower().strip()
+        cid = u["canonical_id"]
+        if uid:
+            _user_names[uid] = cid
+        if fn and ln:
+            _user_names[f"{fn} {ln}"] = cid
+            _user_names[f"{ln}, {fn}"] = cid
+            _user_names[f"{ln} {fn}"] = cid
+
+    def _description_matches_user(desc: str) -> bool:
+        if not desc:
+            return False
+        dl = desc.lower().strip()
+        if dl in _user_names:
+            return True
+        # Substring: check if a full name (2+ words) appears in description
+        for key in _user_names:
+            if " " in key and len(key) >= 4 and key in dl:
+                return True
+        return False
+
+    workspace_count = 0
+    inferred_owner_count = 0
+    for phone in phones:
+        if is_common_area_device(phone):
+            desc = phone.get("description", "")
+            if _description_matches_user(desc):
+                inferred_owner_count += 1
+                logger.info(
+                    "Skipping workspace for %s — description '%s' matches a user",
+                    phone.get("name", "?"), desc,
+                )
+                continue
+            ws_obj = normalize_workspace(phone, cluster=cluster)
+            store.upsert_object(ws_obj)
+            workspace_count += 1
+
+            # Inject is_common_area flag into the stored phone object
+            # so WorkspaceMapper and DeviceMapper can detect common-area phones
+            phone_name = phone.get("name", "")
+            if phone_name:
+                phone_obj = store.get_object(f"phone:{phone_name}")
+                if phone_obj:
+                    pms = dict(phone_obj.get("pre_migration_state") or {})
+                    pms["is_common_area"] = True
+                    store.upsert_object(MigrationObject(
+                        canonical_id=f"phone:{phone_name}",
+                        provenance=Provenance(
+                            source_system="cucm",
+                            source_id=phone.get("pkid", ""),
+                            source_name=phone_name,
+                            cluster=cluster,
+                            extracted_at=datetime.now(timezone.utc),
+                        ),
+                        status=MigrationStatus.NORMALIZED,
+                        pre_migration_state=pms,
+                    ))
+
+    summary["pass1"]["workspaces_classified"] = workspace_count
+    summary["pass1"]["device_owners_inferred"] = inferred_owner_count
+    if workspace_count > 0:
+        logger.info("Classified %d common-area phones as workspaces", workspace_count)
+    if inferred_owner_count > 0:
+        logger.info(
+            "Inferred user ownership for %d phones from description field",
+            inferred_owner_count,
+        )
+
+    # ------------------------------------------------------------------
+    # Unity Connection per-user VM settings (if present)
+    # (from Phase 03 unity_connection.py extract_user_vm_settings())
+    # ------------------------------------------------------------------
+
+    unity_settings = raw_data.get("voicemail", {}).get("unity_user_settings", {})
+    unity_count = 0
+    if isinstance(unity_settings, dict):
+        for userid, settings in unity_settings.items():
+            if isinstance(settings, dict):
+                try:
+                    obj = normalize_unity_vm_settings(userid, settings, cluster=cluster)
+                    store.upsert_object(obj)
+                    unity_count += 1
+                except Exception:
+                    logger.exception("Failed to normalize Unity VM settings for %s", userid)
+
+    summary["pass1"]["unity_vm_settings"] = unity_count
+    if unity_count > 0:
+        logger.info("Normalized %d Unity Connection per-user VM settings", unity_count)
+
+    summary["pass1"]["total"] = total_normalized + workspace_count + unity_count
+
+    # ------------------------------------------------------------------
+    # Pass 2: CrossReferenceBuilder
+    # ------------------------------------------------------------------
+
+    builder = CrossReferenceBuilder(
+        store,
+        default_country_code=default_country_code,
+        site_prefix_rules=site_prefix_rules or [],
+    )
+    pass2_counts = builder.build()
+    summary["pass2"] = pass2_counts
+
+    # ------------------------------------------------------------------
+    # Post-normalization: DECT network grouping
+    # Runs after Pass 2 so compatibility_tier has been classified on all devices.
+    # Groups DECT handsets by device pool into CanonicalDECTNetwork objects.
+    # ------------------------------------------------------------------
+
+    dect_networks = normalize_dect_group(store, dect_inventory=dect_inventory)
+    summary["pass1"]["dect_networks_grouped"] = len(dect_networks)
+    if dect_networks:
+        logger.info("Grouped %d DECT handsets into %d DECT network(s)", sum(
+            len(n.handset_assignments) for n in dect_networks
+        ), len(dect_networks))
+
+    logger.info(
+        "Normalization complete: %d objects normalized, %d cross-refs built",
+        summary["pass1"]["total"],
+        sum(v for v in pass2_counts.values() if isinstance(v, int)),
+    )
+
+    return summary

wxcli/migration/transform/rules.py

@@ -0,0 +1,255 @@
+"""Auto-resolution rules engine for migration decisions.
+
+Applies configurable rules to automatically resolve pending decisions
+without requiring manual user input.  Rules are driven by the config
+dict passed to apply_auto_rules().
+
+(from 03-conflict-detection-engine.md, Auto-Resolution Rules)
+(from 03b-transform-mappers.md section 13, TransformEngine integration)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from wxcli.migration.store import MigrationStore
+
+logger = logging.getLogger(__name__)
+
+
+def _match_rule(rule: dict[str, Any], decision: dict[str, Any]) -> bool:
+    """Check if a rule's ``match`` field matches a decision's context.
+
+    Supports declarative matching only — no eval/exec.
+
+    Match field format (from 03-conflict-detection-engine.md, Auto-Resolution Rules):
+    - Plain key: exact match, or membership if value is a list
+      ``{"cucm_model": ["7841", "7861"]}`` → context["cucm_model"] in list
+    - ``_lte`` suffix: less-than-or-equal comparison
+      ``{"dn_length_lte": 4}`` → context["dn_length"] <= 4
+    - ``_gte`` suffix: greater-than-or-equal comparison
+    - ``_contains`` suffix: substring match
+      ``{"name_contains": "lobby"}`` → "lobby" in context["name"]
+
+    All match fields use AND logic — every field must match.
+    If a match key is not present in the decision's context, the rule is skipped.
+    Non-numeric context values with _lte/_gte operators are skipped (no crash).
+    """
+    match = rule.get("match")
+    if not match or not isinstance(match, dict):
+        return True  # No match field → type-only rule, always matches
+
+    context = decision.get("context", {})
+
+    for key, expected in match.items():
+        # Determine operator suffix
+        if key.endswith("_lte"):
+            base_key = key[:-4]
+            actual = context.get(base_key)
+            if actual is None:
+                return False
+            try:
+                if float(actual) > float(expected):
+                    return False
+            except (ValueError, TypeError):
+                return False  # Non-numeric → skip gracefully
+
+        elif key.endswith("_gte"):
+            base_key = key[:-4]
+            actual = context.get(base_key)
+            if actual is None:
+                return False
+            try:
+                if float(actual) < float(expected):
+                    return False
+            except (ValueError, TypeError):
+                return False
+
+        elif key.endswith("_contains"):
+            base_key = key[:-9]
+            actual = context.get(base_key)
+            if actual is None:
+                return False
+            if not isinstance(actual, str) or not isinstance(expected, str):
+                return False
+            if expected not in actual:
+                return False
+
+        else:
+            # Plain key: exact match or list membership
+            actual = context.get(key)
+            if actual is None:
+                return False
+            if isinstance(expected, list):
+                if actual not in expected:
+                    return False
+            else:
+                if actual != expected:
+                    return False
+
+    return True
+
+
+def _synthesized_reason(dec_type: str, choice: str) -> str:
+    """Default reason when a rule has no explicit `reason` field."""
+    return f"Auto-rule: {dec_type} → {choice}"
+
+
+def _resolve_reason(rule: dict[str, Any], dec_type: str, choice: str) -> str:
+    """Pick the reason string for a matched rule.
+
+    Prefer rule['reason'] if it is a non-empty string. Otherwise (missing,
+    None, empty, or non-string), fall back to the synthesized form and
+    log a warning for the non-string case.
+    """
+    raw = rule.get("reason")
+    if isinstance(raw, str) and raw:
+        return raw
+    if raw is not None and not isinstance(raw, str):
+        logger.warning(
+            "auto-rule reason field is not a string (got %r), using synthesized reason",
+            type(raw).__name__,
+        )
+    return _synthesized_reason(dec_type, choice)
+
+
+def _iter_matching_resolutions(
+    store: MigrationStore,
+    config: dict[str, Any],
+):
+    """Yield ``(decision, choice, reason)`` for every pending decision that
+    a config rule would resolve. Pure read — does NOT mutate the store.
+
+    Both ``apply_auto_rules`` and ``preview_auto_rules`` consume this
+    generator so they cannot drift on matcher semantics.
+
+    Walks the same rules in the same order as the pre-refactor
+    ``apply_auto_rules`` (first-match-wins within a decision type). Skips:
+    - already-resolved decisions (``chosen_option is not None``)
+    - malformed rules (missing type or choice)
+    - rules whose match clause fails
+    - rules whose ``choice`` is not in the decision's ``options`` list
+      (option-validation parity with ``apply_auto_rules``)
+    """
+    rules = config.get("auto_rules", [])
+    if not rules:
+        return
+
+    valid_rules: list[dict[str, Any]] = []
+    for rule in rules:
+        if rule.get("type") and rule.get("choice"):
+            valid_rules.append(rule)
+        else:
+            # Surface config typos — a rule missing `type` or `choice` is
+            # almost always a typo (e.g., "tpe" or missing quotes). Without
+            # this warning, operators see zero auto-applies with no signal
+            # about why. The warning includes the rule dict so they can
+            # grep config.json for the bad entry.
+            logger.warning(
+                "Auto-rule missing 'type' or 'choice' — skipping: %r",
+                rule,
+            )
+
+    if not valid_rules:
+        return
+
+    all_decisions = store.get_all_decisions()
+
+    for dec in all_decisions:
+        if dec.get("chosen_option") is not None:
+            continue
+
+        dec_type = dec.get("type", "")
+
+        for rule in valid_rules:
+            if rule["type"] != dec_type:
+                continue
+            if not _match_rule(rule, dec):
+                continue
+
+            choice = rule["choice"]
+
+            # Option-validation parity with apply_auto_rules.
+            options = dec.get("options", [])
+            valid_ids = {opt["id"] for opt in options if isinstance(opt, dict)}
+            if valid_ids and choice not in valid_ids:
+                logger.warning(
+                    "Auto-rule choice '%s' for decision %s (type=%s) "
+                    "is not a valid option. Valid: %s. Skipping.",
+                    choice,
+                    dec.get("decision_id", ""),
+                    dec_type,
+                    valid_ids,
+                )
+                continue
+
+            reason = _resolve_reason(rule, dec_type, choice)
+            yield dec, choice, reason
+            break  # First matching rule wins for this decision
+
+
+def preview_auto_rules(
+    store: MigrationStore,
+    config: dict[str, Any],
+) -> list[dict[str, Any]]:
+    """Return the list of pending decisions that current config rules would
+    resolve, each augmented with ``auto_choice`` and ``auto_reason`` keys.
+
+    Pure read: does NOT mutate the store. Used by ``classify_decisions``
+    and the CLI preview path in ``wxcli cucm decide --apply-auto``.
+    """
+    result: list[dict[str, Any]] = []
+    for dec, choice, reason in _iter_matching_resolutions(store, config):
+        d = dict(dec)
+        d["auto_choice"] = choice
+        d["auto_reason"] = reason
+        result.append(d)
+    return result
+
+
+def apply_auto_rules(store: MigrationStore, config: dict[str, Any]) -> int:
+    """Apply auto-resolution rules from config to pending decisions.
+
+    Consumes ``_iter_matching_resolutions`` so apply and preview cannot
+    drift on matcher semantics.
+
+    Config format (from 03-conflict-detection-engine.md, Auto-Resolution Rules)::
+
+        {"auto_rules": [
+            {"type": "DEVICE_INCOMPATIBLE", "choice": "skip"},
+            {"type": "DN_AMBIGUOUS",
+             "match": {"dn_length_lte": 4},
+             "choice": "extension_only"},
+        ]}
+
+    Match field supports plain values (exact/list membership), ``_lte``/
+    ``_gte``/``_contains`` suffixes, and AND logic across multiple fields.
+
+    Each resolved decision gets::
+
+        chosen_option = <choice from rule>
+        resolved_by   = "auto_rule"
+        resolved_at   = current UTC timestamp
+
+    Returns count of decisions auto-resolved.
+
+    (from 03-conflict-detection-engine.md, Auto-Resolution Rules)
+    """
+    resolved_count = 0
+    for dec, choice, _reason in _iter_matching_resolutions(store, config):
+        store.resolve_decision(
+            decision_id=dec["decision_id"],
+            chosen_option=choice,
+            resolved_by="auto_rule",
+        )
+        resolved_count += 1
+        logger.debug(
+            "Auto-resolved decision %s (type=%s) with choice='%s'",
+            dec.get("decision_id", ""),
+            dec.get("type", ""),
+            choice,
+        )
+
+    logger.info("Auto-rules resolved %d decision(s)", resolved_count)
+    return resolved_count