wxcli 1.2.0__py3-none-any.whl

wxcli/migration/transform/analyzers/feature_approximation.py

@@ -0,0 +1,227 @@
+"""Feature approximation analyzer for CUCM-to-Webex migration.
+
+Finds CTI route points mapped to auto attendants with complex/unmappable
+scripts, hunt pilots with non-standard algorithms, and call queues with
+agent limit warnings that require approximation in Webex.
+
+FEATURE_APPROXIMATION is a mapper-owned decision type — the feature_mapper
+and routing_mapper already produce these during transform.  This analyzer
+backfills any objects the mappers missed or that acquired warnings after
+initial mapping.
+
+(from 03-conflict-detection-engine.md, linter pattern)
+(from phase-06-analyzers.md, Decision Ownership Table — FEATURE_APPROXIMATION is mapper-owned)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from wxcli.migration.models import DecisionOption, DecisionType
+from wxcli.migration.store import MigrationStore
+from wxcli.migration.transform.analyzers import Analyzer, Decision
+
+
+# ---------------------------------------------------------------------------
+# Approximation detection keywords
+# ---------------------------------------------------------------------------
+# These appear in warnings/errors emitted by feature_mapper and routing_mapper
+# when a CUCM construct cannot be directly mapped to Webex.
+
+_APPROXIMATION_KEYWORDS = (
+    "approximat",
+    "complex script",
+    "fidelity",
+    "not supported",
+    "agent limit",
+)
+
+
+def _extract_approximation_issues(
+    warnings: list[Any], errors: list[Any]
+) -> list[str]:
+    """Extract warning/error strings that indicate approximation was needed."""
+    issues: list[str] = []
+    for source in (warnings, errors):
+        for item in source:
+            if not isinstance(item, str):
+                continue
+            item_lower = item.lower()
+            if any(kw in item_lower for kw in _APPROXIMATION_KEYWORDS):
+                issues.append(item)
+    return issues
+
+
+class FeatureApproximationAnalyzer(Analyzer):
+    """Detects mapped features that required approximation from CUCM to Webex.
+
+    Sweeps three object types for approximation indicators:
+
+    - **auto_attendant** — CTI route points mapped to AA; checks for
+      unmappable scripts (business_hours_menu or after_hours_menu is None)
+      and warning strings about script approximation.
+
+    - **hunt_group** — Hunt pilots with non-standard algorithms; checks
+      for warning strings about algorithm approximation.
+
+    - **call_queue** — Queues that exceeded Webex agent limits or had
+      unsupported features; checks for agent limit warnings.
+
+    Skips objects that already have a mapper-produced FEATURE_APPROXIMATION
+    decision.
+
+    (from 03-conflict-detection-engine.md, feature approximation linter)
+    """
+
+    name = "feature_approximation"
+    decision_types = [DecisionType.FEATURE_APPROXIMATION]
+    depends_on: list[str] = []
+
+    # Object types to sweep, with type-specific checks
+    _FEATURE_TYPES = ("auto_attendant", "hunt_group", "call_queue")
+
+    def analyze(self, store: MigrationStore) -> list[Decision]:
+        """Sweep AA, HG, and CQ objects for approximation indicators."""
+        # Existing mapper-produced decisions indexed by canonical_id
+        existing = self._get_existing_decisions_for_type(
+            store, DecisionType.FEATURE_APPROXIMATION
+        )
+
+        decisions: list[Decision] = []
+
+        for feature_type in self._FEATURE_TYPES:
+            objects = store.get_objects(feature_type)
+            for obj in objects:
+                canonical_id = obj.get("canonical_id", "")
+
+                # Skip if mapper already produced a decision for this object
+                if canonical_id in existing:
+                    continue
+
+                issues = self._detect_approximation_issues(feature_type, obj)
+                if not issues:
+                    continue
+
+                severity = self._determine_severity(feature_type, obj, issues)
+                name = obj.get("name") or obj.get("display_name") or canonical_id
+
+                summary = (
+                    f"{feature_type} '{name}' requires approximation: "
+                    f"{'; '.join(issues[:3])}"
+                )
+                if len(issues) > 3:
+                    summary += f" (+{len(issues) - 3} more)"
+
+                context = {
+                    "feature_type": feature_type,
+                    "canonical_id": canonical_id,
+                    "name": name,
+                    "approximation_issues": issues,
+                }
+
+                options = [
+                    DecisionOption(
+                        id="accept",
+                        label="Accept approximation",
+                        impact=(
+                            f"{feature_type} '{name}' migrated with best-effort "
+                            f"approximation ({len(issues)} issue(s))"
+                        ),
+                    ),
+                    DecisionOption(
+                        id="manual",
+                        label="Configure manually post-migration",
+                        impact=(
+                            f"{feature_type} '{name}' flagged for manual "
+                            f"post-migration configuration"
+                        ),
+                    ),
+                    DecisionOption(
+                        id="skip",
+                        label="Skip this feature",
+                        impact=f"{feature_type} '{name}' excluded from migration",
+                    ),
+                ]
+
+                decision = self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.FEATURE_APPROXIMATION,
+                    severity=severity,
+                    summary=summary,
+                    context=context,
+                    options=options,
+                    affected_objects=[canonical_id],
+                )
+                decisions.append(decision)
+
+        return decisions
+
+    def fingerprint(self, decision_type: DecisionType, context: dict[str, Any]) -> str:
+        """Deterministic fingerprint from canonical_id + sorted approximation issues."""
+        return self._hash_fingerprint({
+            "type": decision_type.value,
+            "canonical_id": context.get("canonical_id", ""),
+            "approximation_issues": sorted(context.get("approximation_issues", [])),
+        })
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _detect_approximation_issues(
+        feature_type: str, obj: dict[str, Any]
+    ) -> list[str]:
+        """Detect all approximation issues for a given feature object.
+
+        Checks warnings/errors lists for approximation keywords, plus
+        type-specific structural checks (e.g., None menus on auto_attendants).
+        """
+        warnings = obj.get("warnings") or []
+        errors = obj.get("errors") or []
+        issues = _extract_approximation_issues(warnings, errors)
+
+        # Type-specific structural checks
+        if feature_type == "auto_attendant":
+            # None menus indicate an unmappable CTI route point script
+            if obj.get("business_hours_menu") is None:
+                issue = "business_hours_menu is None (unmappable CTI route point script)"
+                if issue not in issues:
+                    issues.append(issue)
+            if obj.get("after_hours_menu") is None:
+                issue = "after_hours_menu is None (unmappable CTI route point script)"
+                if issue not in issues:
+                    issues.append(issue)
+
+        return issues
+
+    @staticmethod
+    def _determine_severity(
+        feature_type: str,
+        obj: dict[str, Any],
+        issues: list[str],
+    ) -> str:
+        """Determine decision severity based on feature type and issues.
+
+        HIGH:   auto_attendant with None menus (completely unmappable)
+        MEDIUM: call_queue agent limit issues, hunt_group algorithm issues
+        LOW:    minor approximations (warning-only, no structural problems)
+        """
+        if feature_type == "auto_attendant":
+            # Unmappable menus are HIGH severity
+            if obj.get("business_hours_menu") is None or obj.get("after_hours_menu") is None:
+                return "HIGH"
+
+        # Agent limit issues are MEDIUM
+        for issue in issues:
+            if "agent limit" in issue.lower():
+                return "MEDIUM"
+
+        # Check for strong approximation keywords -> MEDIUM
+        for issue in issues:
+            issue_lower = issue.lower()
+            if any(kw in issue_lower for kw in ("complex script", "not supported")):
+                return "MEDIUM"
+
+        # Minor approximations
+        return "LOW"

wxcli/migration/transform/analyzers/layout_overflow.py

@@ -0,0 +1,174 @@
+"""Layout overflow analyzer — detects button count overflow and KEM incompatibility.
+
+Sweeps CanonicalDeviceLayout objects cross-referenced with CanonicalDevice objects.
+Detects phones where the CUCM button template assigns more line keys than the Webex
+device model supports, or where KEM buttons exist but the Webex model doesn't support KEM.
+
+Sources:
+- tier2-phase2-phone-config-design.md §5.1
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from wxcli.migration.models import DecisionOption, DecisionType
+from wxcli.migration.store import MigrationStore
+from wxcli.migration.transform.analyzers import Analyzer, Decision
+
+logger = logging.getLogger(__name__)
+
+# Phone model → max line key count — imported from the single source of truth
+from wxcli.migration.phone_models import MODEL_LINE_KEY_COUNTS as _MODEL_LINE_KEY_COUNTS
+
+# Models that support KEM expansion modules
+_KEM_SUPPORTED_MODELS: set[str] = {
+    "8845", "8851", "8861", "8865",
+    "9851", "9861",
+    "6851", "6861", "6871",
+}
+
+
+def _extract_model_number(model: str) -> str:
+    """Extract numeric model identifier from full model string.
+
+    Examples:
+        "CP-8845" → "8845"
+        "Cisco 9841" → "9841"
+        "DMS Cisco 8845" → "8845"
+    """
+    if not model:
+        return ""
+    # Strip common prefixes
+    cleaned = model.replace("CP-", "").replace("Cisco ", "").replace("DMS ", "")
+    # Take first token that looks like a model number (4 digits)
+    for token in cleaned.split():
+        digits = "".join(c for c in token if c.isdigit())
+        if len(digits) >= 4:
+            return digits
+    # Fallback: return cleaned string
+    return cleaned.strip()
+
+
+class LayoutOverflowAnalyzer(Analyzer):
+    """Detects layout overflow (too many line keys) and KEM incompatibility.
+
+    Sweeps all CanonicalDeviceLayout objects and checks:
+    - resolved_line_keys count vs device model max_line_count
+    - resolved_kem_keys present but device model doesn't support KEM
+    """
+
+    name = "layout_overflow"
+    decision_types = [DecisionType.FEATURE_APPROXIMATION]
+    depends_on: list[str] = []
+
+    def analyze(self, store: MigrationStore) -> list[Decision]:
+        decisions: list[Decision] = []
+
+        layouts = store.get_objects("device_layout")
+        if not layouts:
+            return decisions
+
+        for layout in layouts:
+            device_cid = layout.get("device_canonical_id", "")
+            if not device_cid:
+                continue
+
+            device = store.get_object(device_cid)
+            if device is None:
+                continue
+
+            model_raw = device.get("model", "")
+            model_num = _extract_model_number(model_raw)
+
+            resolved_keys = layout.get("resolved_line_keys", [])
+            kem_keys = layout.get("resolved_kem_keys", [])
+            layout_cid = layout.get("canonical_id", "")
+
+            # Check 1: Line key overflow
+            max_keys = _MODEL_LINE_KEY_COUNTS.get(model_num)
+            if max_keys is not None and len(resolved_keys) > max_keys:
+                context = {
+                    "layout_canonical_id": layout_cid,
+                    "device_canonical_id": device_cid,
+                    "model": model_raw,
+                    "model_number": model_num,
+                    "max_line_keys": max_keys,
+                    "actual_line_keys": len(resolved_keys),
+                    "overflow_count": len(resolved_keys) - max_keys,
+                    "overflow_type": "line_key_count",
+                }
+                options = [
+                    DecisionOption(
+                        id="accept",
+                        label=f"Truncate to first {max_keys} keys",
+                        impact=f"{len(resolved_keys) - max_keys} line keys will be dropped",
+                    ),
+                    DecisionOption(
+                        id="manual",
+                        label="Create custom line key template",
+                        impact="Manually assign line keys to fit device capacity",
+                    ),
+                    DecisionOption(
+                        id="skip",
+                        label="Use Webex default layout",
+                        impact="Phone will use Webex default line key assignment",
+                    ),
+                ]
+                decisions.append(self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.FEATURE_APPROXIMATION,
+                    severity="MEDIUM",
+                    summary=(
+                        f"Line key overflow on {model_raw}: "
+                        f"{len(resolved_keys)} keys exceeds max {max_keys}"
+                    ),
+                    context=context,
+                    options=options,
+                    affected_objects=[layout_cid, device_cid],
+                ))
+
+            # Check 2: KEM buttons on non-KEM device
+            if kem_keys and model_num not in _KEM_SUPPORTED_MODELS:
+                context = {
+                    "layout_canonical_id": layout_cid,
+                    "device_canonical_id": device_cid,
+                    "model": model_raw,
+                    "model_number": model_num,
+                    "kem_key_count": len(kem_keys),
+                    "overflow_type": "kem_not_supported",
+                }
+                options = [
+                    DecisionOption(
+                        id="accept_loss",
+                        label="KEM buttons will be lost",
+                        impact=f"{len(kem_keys)} KEM buttons cannot be migrated — device does not support KEM",
+                    ),
+                    DecisionOption(
+                        id="manual",
+                        label="Attach compatible KEM to new device",
+                        impact="Replace device with KEM-compatible model or add KEM module",
+                    ),
+                ]
+                decisions.append(self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.FEATURE_APPROXIMATION,
+                    severity="MEDIUM",
+                    summary=(
+                        f"KEM buttons on {model_raw} which does not support KEM: "
+                        f"{len(kem_keys)} KEM keys will be lost"
+                    ),
+                    context=context,
+                    options=options,
+                    affected_objects=[layout_cid, device_cid],
+                ))
+
+        return decisions
+
+    def fingerprint(self, decision_type: DecisionType, context: dict[str, Any]) -> str:
+        return self._hash_fingerprint({
+            "device_canonical_id": context.get("device_canonical_id", ""),
+            "overflow_type": context.get("overflow_type", ""),
+            "model": context.get("model", ""),
+        })

wxcli/migration/transform/analyzers/location_ambiguity.py

@@ -0,0 +1,184 @@
+"""Location ambiguity analyzer — finds locations with ambiguous device pool mappings.
+
+Mapper-owned decision type: location_mapper may already produce LOCATION_AMBIGUOUS
+decisions. This analyzer backfills any locations the mapper missed or detects
+cross-object ambiguities that emerge after the full inventory is mapped.
+
+(from 03-conflict-detection-engine.md, location ambiguity linter)
+(from phase-06-analyzers.md, Decision Ownership Table — mapper-owned)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from wxcli.migration.models import DecisionOption, DecisionType
+from wxcli.migration.store import MigrationStore
+from wxcli.migration.transform.analyzers import Analyzer, Decision
+
+
+class LocationAmbiguityAnalyzer(Analyzer):
+    """Detects locations with ambiguous CUCM device pool consolidation.
+
+    Sweeps all location objects and flags those whose ``warnings`` list
+    contains ambiguity indicators (e.g., multiple device pools consolidated
+    with conflicting CUCM location references).
+
+    Skips locations that already have a mapper-produced LOCATION_AMBIGUOUS decision.
+    """
+
+    name = "location_ambiguity"
+    decision_types = [DecisionType.LOCATION_AMBIGUOUS]
+    depends_on: list[str] = []
+
+    # Substrings in warnings that indicate location ambiguity
+    _AMBIGUITY_MARKERS = ("ambiguous", "conflicting", "multiple cucm locations", "mismatch")
+
+    def analyze(self, store: MigrationStore) -> list[Decision]:
+        decisions: list[Decision] = []
+
+        # Get existing mapper-produced decisions indexed by affected object canonical_id
+        existing_ambiguous = self._get_existing_decisions_for_type(
+            store, DecisionType.LOCATION_AMBIGUOUS
+        )
+
+        locations = store.get_objects("location")
+
+        for location in locations:
+            canonical_id = location.get("canonical_id", "")
+
+            # Skip if mapper already produced a LOCATION_AMBIGUOUS decision for this location
+            if canonical_id in existing_ambiguous:
+                continue
+
+            ambiguity_reasons: list[str] = []
+
+            # Check 1: warnings/errors containing ambiguity markers
+            warnings = location.get("warnings", [])
+            errors = location.get("errors", [])
+            all_messages = warnings + errors
+
+            for msg in all_messages:
+                if any(marker in msg.lower() for marker in self._AMBIGUITY_MARKERS):
+                    ambiguity_reasons.append(msg)
+
+            # Check 2: multiple consolidated device pools (cross-object signal)
+            # A location consolidating 3+ device pools is inherently ambiguous —
+            # the mapper may not have flagged it if no CUCM location mismatch
+            # was detected, but the admin should still review the consolidation.
+            pool_names = location.get("cucm_device_pool_names", [])
+            if len(pool_names) >= 3 and not ambiguity_reasons:
+                ambiguity_reasons.append(
+                    f"Location consolidates {len(pool_names)} device pools: "
+                    f"{', '.join(pool_names[:5])}"
+                )
+
+            if not ambiguity_reasons:
+                continue
+
+            decisions.append(self._build_ambiguous_decision(
+                store, location, ambiguity_reasons
+            ))
+
+        return decisions
+
+    def fingerprint(self, decision_type: DecisionType, context: dict[str, Any]) -> str:
+        pool_names = context.get("cucm_device_pool_names", [])
+        return self._hash_fingerprint({
+            "canonical_id": context.get("canonical_id", ""),
+            "cucm_device_pool_names": sorted(pool_names),
+        })
+
+    # ------------------------------------------------------------------
+    # Decision builder
+    # ------------------------------------------------------------------
+
+    def _build_ambiguous_decision(
+        self,
+        store: MigrationStore,
+        location: dict[str, Any],
+        ambiguity_warnings: list[str],
+    ) -> Decision:
+        canonical_id = location.get("canonical_id", "")
+        name = location.get("name", "unknown")
+        pool_names = location.get("cucm_device_pool_names", [])
+
+        # Count devices + users depending on this location's device pools
+        dependent_count = 0
+        for pool_name in pool_names:
+            pool_id = f"device_pool:{pool_name}"
+            dependent_count += len(store.get_cross_refs(
+                to_id=pool_id, relationship="device_in_pool",
+            ))
+            dependent_count += len(store.get_cross_refs(
+                to_id=pool_id, relationship="common_area_device_in_pool",
+            ))
+
+        has_address = bool(
+            location.get("address", {}).get("address1")
+            if isinstance(location.get("address"), dict)
+            else None
+        )
+
+        context = {
+            "canonical_id": canonical_id,
+            "location_name": name,
+            "cucm_device_pool_names": pool_names,
+            "warnings": ambiguity_warnings,
+            "dependent_device_count": dependent_count,
+            "has_address": has_address,
+        }
+        options = [
+            DecisionOption(
+                id="accept",
+                label="Accept this location mapping",
+                impact=f"Location '{name}' will be created with consolidated device pools: "
+                       f"{', '.join(pool_names) or 'none'}",
+            ),
+            DecisionOption(
+                id="provide_address",
+                label="Provide address for this location",
+                impact=f"Location '{name}' needs a street address to create in Webex. "
+                       f"Use 'wxcli cucm decide' to supply address1, city, state, postal_code, country.",
+            ),
+            DecisionOption(
+                id="reassign",
+                label="Manually assign to different location",
+                impact=f"Device pools {', '.join(pool_names) or 'none'} will be "
+                       f"reassigned to a user-specified location",
+            ),
+            DecisionOption(
+                id="split",
+                label="Split into separate locations",
+                impact=f"Each device pool will become its own Webex location "
+                       f"({len(pool_names)} locations)",
+            ),
+        ]
+
+        # Only offer skip if no devices depend on this location
+        if dependent_count == 0:
+            options.append(DecisionOption(
+                id="skip",
+                label="Skip this location (no devices affected)",
+                impact=f"Location '{name}' will not be migrated (0 devices in its pools)",
+            ))
+        else:
+            # Make the impact of NOT having an address very clear
+            options[1] = DecisionOption(
+                id="provide_address",
+                label=f"Provide address for this location ({dependent_count} devices depend on it)",
+                impact=f"Location '{name}' has {dependent_count} devices in its pools. "
+                       f"A street address is REQUIRED to create this location in Webex. "
+                       f"Skipping is not available because it would block all {dependent_count} devices.",
+            )
+
+        return self._create_decision(
+            store=store,
+            decision_type=DecisionType.LOCATION_AMBIGUOUS,
+            severity="HIGH",
+            summary=f"Location '{name}' has ambiguous device pool mapping: "
+                    f"{'; '.join(ambiguity_warnings[:2])}",
+            context=context,
+            options=options,
+            affected_objects=[canonical_id],
+        )