wxcli 1.2.0__py3-none-any.whl

wxcli/migration/transform/analyzers/device_compatibility.py

@@ -0,0 +1,122 @@
+"""Device compatibility analyzer — finds incompatible devices.
+
+Mapper-owned decision type: device_mapper may already produce DEVICE_INCOMPATIBLE
+decisions. This analyzer backfills any devices the mapper missed (e.g., devices
+added after initial mapping).
+
+Convertible devices are NOT surfaced as decisions. Convertibility is a phone
+model classification (``compatibility_tier == 'convertible'``), not an operator
+choice — the planner unconditionally emits an activation-code op for those.
+
+(from 03-conflict-detection-engine.md, device compatibility 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 DeviceCompatibilityAnalyzer(Analyzer):
+    """Detects devices that are incompatible with Webex Calling.
+
+    Sweeps all device objects and checks ``compatibility_tier``:
+    - ``incompatible`` -> DEVICE_INCOMPATIBLE decision
+    - ``convertible``  -> no decision (planner emits conversion op unconditionally)
+    - ``native_mpp``   -> no decision needed
+
+    Skips devices that already have a mapper-produced decision for the same type.
+    """
+
+    name = "device_compatibility"
+    decision_types = [DecisionType.DEVICE_INCOMPATIBLE]
+    depends_on: list[str] = []
+
+    def analyze(self, store: MigrationStore) -> list[Decision]:
+        decisions: list[Decision] = []
+
+        # Get existing mapper-produced decisions indexed by affected object canonical_id
+        existing_incompatible = self._get_existing_decisions_for_type(
+            store, DecisionType.DEVICE_INCOMPATIBLE
+        )
+
+        devices = store.get_objects("device")
+
+        for device in devices:
+            canonical_id = device.get("canonical_id", "")
+            tier = device.get("compatibility_tier")
+
+            if tier in ("webex_app", "infrastructure", "dect", "convertible"):
+                # Software phones transition to Webex App; infrastructure devices
+                # (CTI, CER, gateways) are CUCM-only; DECT is handled via DECT network
+                # provisioning; convertible devices always convert (no operator choice).
+                continue
+
+            elif tier == "incompatible":
+                # Skip if mapper already produced this decision for this device
+                if canonical_id in existing_incompatible:
+                    continue
+                decisions.append(self._build_incompatible_decision(store, device))
+
+            # native_mpp and None — no decision needed
+
+        return decisions
+
+    def fingerprint(self, decision_type: DecisionType, context: dict[str, Any]) -> str:
+        return self._hash_fingerprint({
+            "canonical_id": context.get("canonical_id", ""),
+            "model": context.get("model", ""),
+            "compatibility_tier": context.get("compatibility_tier", ""),
+        })
+
+    # ------------------------------------------------------------------
+    # Decision builders
+    # ------------------------------------------------------------------
+
+    def _build_incompatible_decision(
+        self, store: MigrationStore, device: dict[str, Any]
+    ) -> Decision:
+        canonical_id = device.get("canonical_id", "")
+        model = device.get("model", "unknown")
+        mac = device.get("mac", "")
+        cucm_device_name = device.get("cucm_device_name", "")
+        owner_canonical_id = device.get("owner_canonical_id", "")
+
+        context = {
+            "canonical_id": canonical_id,
+            "model": model,
+            "mac": mac,
+            "cucm_device_name": cucm_device_name,
+            "owner_canonical_id": owner_canonical_id,
+            "compatibility_tier": "incompatible",
+        }
+        options = [
+            DecisionOption(
+                id="skip",
+                label="Skip device",
+                impact=f"Device {model} ({cucm_device_name}) will not be migrated",
+            ),
+            DecisionOption(
+                id="manual",
+                label="Handle manually",
+                impact=f"Device {model} ({cucm_device_name}) flagged for manual replacement",
+            ),
+        ]
+        affected = [canonical_id]
+        if owner_canonical_id:
+            affected.append(owner_canonical_id)
+
+        return self._create_decision(
+            store=store,
+            decision_type=DecisionType.DEVICE_INCOMPATIBLE,
+            severity="MEDIUM",
+            summary=f"Device {model} ({cucm_device_name}) is incompatible with Webex Calling",
+            context=context,
+            options=options,
+            affected_objects=affected,
+        )
+

wxcli/migration/transform/analyzers/dn_ambiguity.py

@@ -0,0 +1,131 @@
+"""DN ambiguity analyzer — finds lines with AMBIGUOUS E.164 classification.
+
+The line_mapper's E.164 normalization algorithm classifies each DN as
+EXTENSION, NATIONAL, E164, or AMBIGUOUS.  This analyzer surfaces the
+AMBIGUOUS cases so a human can make the call.
+
+Decision ownership: MAPPER-OWNED (line_mapper produces DN_AMBIGUOUS decisions).
+This analyzer checks for existing mapper decisions before creating new ones.
+
+(from 03-conflict-detection-engine.md, DN ambiguity detection)
+(from 03b-transform-mappers.md, line_mapper E.164 algorithm lines 208-211)
+(from 07-idempotency-resumability.md, fingerprint-based identity)
+"""
+
+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 DNAmbiguityAnalyzer(Analyzer):
+    """Finds DNs where E.164 classification is AMBIGUOUS.
+
+    The line_mapper may already have produced DN_AMBIGUOUS decisions for some
+    lines.  This analyzer only creates decisions for ambiguous lines that
+    don't already have one, acting as a safety net for anything the mapper
+    missed.
+    """
+
+    name = "dn_ambiguity"
+    decision_types = [DecisionType.DN_AMBIGUOUS]
+
+    def analyze(self, store: MigrationStore) -> list[Decision]:
+        """Sweep all lines, find AMBIGUOUS classification, skip already-decided."""
+        decisions: list[Decision] = []
+
+        # Step 1: Get existing mapper-produced DN_AMBIGUOUS decisions
+        existing = self._get_existing_decisions_for_type(store, DecisionType.DN_AMBIGUOUS)
+
+        # Step 2: Load all lines and filter for AMBIGUOUS classification
+        lines = store.get_objects("line")
+        if not lines:
+            return decisions
+
+        for line in lines:
+            classification = line.get("classification")
+            if classification != "AMBIGUOUS":
+                continue
+
+            canonical_id = line.get("canonical_id", "")
+            if not canonical_id:
+                continue
+
+            # Skip if mapper already produced a decision for this line
+            if canonical_id in existing:
+                continue
+
+            dn_pattern = line.get("cucm_pattern", "")
+            partition = line.get("route_partition_name", "")
+            # Count fixed (non-wildcard) digits after stripping + prefix
+            # e.g., "+1555XXXX" -> "1555XXXX" -> count chars that aren't X/x/. -> 4
+            stripped = dn_pattern.lstrip("+")
+            dn_length = sum(1 for c in stripped if c not in "Xx.![]")
+
+            severity = "LOW" if dn_length <= 4 else "MEDIUM"
+
+            context = {
+                "dn": dn_pattern,
+                "partition": partition,
+                "dn_length": dn_length,
+                "canonical_id": canonical_id,
+            }
+
+            options = [
+                DecisionOption(
+                    id="extension_only",
+                    label="Treat as Extension",
+                    impact=f"Map '{dn_pattern}' as internal extension only — no DID",
+                ),
+                DecisionOption(
+                    id="national",
+                    label="Treat as National Number",
+                    impact=f"Map '{dn_pattern}' as national-format DID",
+                ),
+                DecisionOption(
+                    id="e164",
+                    label="Treat as E.164",
+                    impact=f"Map '{dn_pattern}' as full E.164 DID with + prefix",
+                ),
+                DecisionOption(
+                    id="skip",
+                    label="Skip",
+                    impact="Leave DN unmapped — manual intervention required",
+                ),
+            ]
+
+            decision = self._create_decision(
+                store=store,
+                decision_type=DecisionType.DN_AMBIGUOUS,
+                severity=severity,
+                summary=(
+                    f"DN '{dn_pattern}' in partition '{partition}' has ambiguous "
+                    f"E.164 classification ({dn_length} digits)"
+                ),
+                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 DN pattern, partition, and line ID.
+
+        Includes:
+        - dn (the pattern that's ambiguous)
+        - partition (routing scope — different partitions are different decisions)
+        - canonical_id (the specific line object)
+
+        (from 07-idempotency-resumability.md lines 30-43)
+        """
+        return self._hash_fingerprint({
+            "type": decision_type.value,
+            "dn": context.get("dn"),
+            "partition": context.get("partition"),
+            "canonical_id": context.get("canonical_id"),
+        })

wxcli/migration/transform/analyzers/duplicate_user.py

@@ -0,0 +1,221 @@
+"""Duplicate user analyzer — finds users with matching email or name across CUCM inventory.
+
+Detects users that would collide in Webex because they share the same email
+address, or users without emails who share the same (first_name, last_name)
+pair.  Duplicate users block migration because Webex requires unique email
+identities.
+
+Decision ownership: ANALYZER-OWNED (no mapper produces DUPLICATE_USER).
+
+(from 03-conflict-detection-engine.md, duplicate user detection)
+(from 07-idempotency-resumability.md, fingerprint-based identity)
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+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 DuplicateUserAnalyzer(Analyzer):
+    """Finds users with matching email or name across CUCM inventory.
+
+    Webex requires each person to have a unique email address.  This analyzer
+    detects two collision patterns:
+
+    1. **Email collisions**: 2+ users share the same email (case-insensitive).
+    2. **Name collisions (no email)**: 2+ users with empty emails share the
+       same (first_name, last_name) pair — likely the same person entered
+       multiple times in CUCM.
+
+    Both patterns produce DUPLICATE_USER decisions with HIGH severity since
+    they block migration.
+    """
+
+    name = "duplicate_user"
+    decision_types = [DecisionType.DUPLICATE_USER]
+
+    def analyze(self, store: MigrationStore) -> list[Decision]:
+        """Sweep all users, group by email and name, flag duplicates."""
+        decisions: list[Decision] = []
+
+        users = store.get_objects("user")
+        if not users:
+            return decisions
+
+        # Step 1: Group users by lowercase email
+        email_groups: dict[str, list[dict[str, Any]]] = defaultdict(list)
+        # Track users with no email for name-based duplicate check
+        no_email_users: list[dict[str, Any]] = []
+
+        for user in users:
+            emails = user.get("emails", [])
+            if emails:
+                for email in emails:
+                    email_lower = email.strip().lower()
+                    if email_lower:
+                        email_groups[email_lower].append(user)
+            else:
+                no_email_users.append(user)
+
+        # Step 2: Produce decisions for email-based duplicates (2+ users per email)
+        seen_ids: set[str] = set()  # track which users already have a decision
+
+        for email, group_users in sorted(email_groups.items()):
+            if len(group_users) < 2:
+                continue
+
+            # Deduplicate by canonical_id within the group (a user with multiple
+            # emails could appear twice in the same group)
+            unique_users: dict[str, dict[str, Any]] = {}
+            for u in group_users:
+                cid = u.get("canonical_id", "")
+                if cid:
+                    unique_users[cid] = u
+
+            if len(unique_users) < 2:
+                continue
+
+            user_ids = sorted(unique_users.keys())
+            user_names = [
+                unique_users[uid].get("display_name")
+                or f"{unique_users[uid].get('first_name', '')} {unique_users[uid].get('last_name', '')}".strip()
+                or uid
+                for uid in user_ids
+            ]
+
+            context = {
+                "email": email,
+                "user_ids": user_ids,
+                "user_names": user_names,
+            }
+
+            options = [
+                DecisionOption(
+                    id="merge",
+                    label="Merge",
+                    impact=f"Merge {len(user_ids)} users into single Webex person",
+                ),
+                DecisionOption(
+                    id="keep_primary",
+                    label="Keep Primary",
+                    impact=f"Keep first user, skip {len(user_ids) - 1} others",
+                ),
+                DecisionOption(
+                    id="skip_all",
+                    label="Skip All",
+                    impact=f"Skip all {len(user_ids)} duplicate users",
+                ),
+                DecisionOption(
+                    id="manual",
+                    label="Manual Resolution",
+                    impact="Flag for manual review and resolution",
+                ),
+            ]
+
+            decision = self._create_decision(
+                store=store,
+                decision_type=DecisionType.DUPLICATE_USER,
+                severity="HIGH",
+                summary=f"Email {email} shared by {len(user_ids)} users",
+                context=context,
+                options=options,
+                affected_objects=user_ids,
+            )
+            decisions.append(decision)
+            seen_ids.update(user_ids)
+
+        # Step 3: Check no-email users for (first_name, last_name) collisions
+        name_groups: dict[tuple[str, str], list[dict[str, Any]]] = defaultdict(list)
+
+        for user in no_email_users:
+            cid = user.get("canonical_id", "")
+            if cid in seen_ids:
+                continue  # already covered by an email-based decision
+
+            first = (user.get("first_name") or "").strip().lower()
+            last = (user.get("last_name") or "").strip().lower()
+            if first or last:
+                name_groups[(first, last)].append(user)
+
+        for (first, last), group_users in sorted(name_groups.items()):
+            if len(group_users) < 2:
+                continue
+
+            user_ids = sorted(u.get("canonical_id", "") for u in group_users if u.get("canonical_id"))
+            if len(user_ids) < 2:
+                continue
+
+            display_name = f"{first} {last}".strip()
+            user_names = [
+                u.get("display_name") or display_name or u.get("canonical_id", "")
+                for u in group_users
+                if u.get("canonical_id")
+            ]
+
+            # Use a synthetic email key for context — no real email exists
+            name_key = f"<no-email>:{first}:{last}"
+
+            context = {
+                "email": name_key,
+                "user_ids": user_ids,
+                "user_names": sorted(user_names),
+            }
+
+            options = [
+                DecisionOption(
+                    id="merge",
+                    label="Merge",
+                    impact=f"Merge {len(user_ids)} users into single Webex person",
+                ),
+                DecisionOption(
+                    id="keep_primary",
+                    label="Keep Primary",
+                    impact=f"Keep first user, skip {len(user_ids) - 1} others",
+                ),
+                DecisionOption(
+                    id="skip_all",
+                    label="Skip All",
+                    impact=f"Skip all {len(user_ids)} duplicate users",
+                ),
+                DecisionOption(
+                    id="manual",
+                    label="Manual Resolution",
+                    impact="Flag for manual review and resolution",
+                ),
+            ]
+
+            decision = self._create_decision(
+                store=store,
+                decision_type=DecisionType.DUPLICATE_USER,
+                severity="HIGH",
+                summary=(
+                    f"Name '{display_name}' shared by {len(user_ids)} users "
+                    f"(no email set)"
+                ),
+                context=context,
+                options=options,
+                affected_objects=user_ids,
+            )
+            decisions.append(decision)
+
+        return decisions
+
+    def fingerprint(self, decision_type: DecisionType, context: dict[str, Any]) -> str:
+        """Deterministic fingerprint from shared email and affected user IDs.
+
+        Includes:
+        - email (the shared email, or synthetic name key for no-email dupes)
+        - sorted user canonical_ids (all users in the duplicate group)
+
+        (from 07-idempotency-resumability.md lines 30-43)
+        """
+        return self._hash_fingerprint({
+            "type": decision_type.value,
+            "email": context.get("email"),
+            "user_ids": sorted(context.get("user_ids", [])),
+        })

wxcli/migration/transform/analyzers/extension_conflict.py

@@ -0,0 +1,173 @@
+"""Extension conflict analyzer — finds DNs sharing the same extension within a location.
+
+Detects lines that would collide in Webex Calling because they share the same
+extension number within the same location.  CUCM allows this via partitions,
+but Webex Calling enforces unique extensions per location.
+
+Decision ownership: ANALYZER-OWNED (no mapper produces EXTENSION_CONFLICT).
+
+(from 03-conflict-detection-engine.md, extension conflict detection)
+(from 07-idempotency-resumability.md, fingerprint-based identity)
+"""
+
+from __future__ import annotations
+
+import json
+from collections import defaultdict
+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 ExtensionConflictAnalyzer(Analyzer):
+    """Finds extension conflicts within the same Webex Calling location.
+
+    CUCM allows multiple DNs with the same pattern in different partitions.
+    Webex Calling requires unique extensions per location.  This analyzer
+    groups lines by (extension, location) and flags collisions.
+
+    Location resolution: line → device (via device_has_dn cross-ref) →
+    device.location_canonical_id.
+    """
+
+    name = "extension_conflict"
+    decision_types = [DecisionType.EXTENSION_CONFLICT]
+
+    def analyze(self, store: MigrationStore) -> list[Decision]:
+        """Sweep all lines, group by (extension, location), flag conflicts."""
+        decisions: list[Decision] = []
+
+        # Step 1: Load all lines and build a map of canonical_id → line data
+        lines = store.get_objects("line")
+        if not lines:
+            return decisions
+
+        line_by_id: dict[str, dict[str, Any]] = {}
+        for line in lines:
+            cid = line.get("canonical_id", "")
+            if cid:
+                line_by_id[cid] = line
+
+        # Step 2: For each line, resolve its location via:
+        #   line ←(device_has_dn)← device → device.location_canonical_id
+        # Query cross_refs where relationship='device_has_dn' and to_id is a line
+        line_location: dict[str, str] = {}  # line canonical_id → location canonical_id
+
+        device_rows = store.conn.execute(
+            "SELECT from_id, to_id FROM cross_refs WHERE relationship = 'device_has_dn'"
+        ).fetchall()
+
+        # Build line → device(s) mapping
+        line_to_devices: dict[str, list[str]] = defaultdict(list)
+        for row in device_rows:
+            line_to_devices[row["to_id"]].append(row["from_id"])
+
+        # Load all devices once for location lookups
+        devices = store.get_objects("device")
+        device_location: dict[str, str] = {}
+        for dev in devices:
+            dev_cid = dev.get("canonical_id", "")
+            loc_cid = dev.get("location_canonical_id", "")
+            if dev_cid and loc_cid:
+                device_location[dev_cid] = loc_cid
+
+        # Resolve each line's location via its owning device
+        for line_cid in line_by_id:
+            owning_devices = line_to_devices.get(line_cid, [])
+            for dev_cid in owning_devices:
+                loc = device_location.get(dev_cid)
+                if loc:
+                    line_location[line_cid] = loc
+                    break  # use the first device that has a location
+
+        # Step 3: Group lines by (extension, location)
+        groups: dict[tuple[str, str], list[str]] = defaultdict(list)
+        for line_cid, line_data in line_by_id.items():
+            ext = line_data.get("extension")
+            loc = line_location.get(line_cid)
+            if ext and loc:
+                groups[(ext, loc)].append(line_cid)
+
+        # Step 4: Produce decisions for groups with 2+ lines
+        for (ext, loc_cid), conflicting_ids in sorted(groups.items()):
+            if len(conflicting_ids) < 2:
+                continue
+
+            severity = "HIGH" if len(conflicting_ids) >= 3 else "MEDIUM"
+
+            # Build context with details about each conflicting line
+            line_details = []
+            for cid in sorted(conflicting_ids):
+                ld = line_by_id.get(cid, {})
+                line_details.append({
+                    "canonical_id": cid,
+                    "cucm_pattern": ld.get("cucm_pattern"),
+                    "route_partition_name": ld.get("route_partition_name"),
+                })
+
+            context = {
+                "extension": ext,
+                "location_canonical_id": loc_cid,
+                "conflict_count": len(conflicting_ids),
+                "conflicting_lines": line_details,
+            }
+
+            options = [
+                DecisionOption(
+                    id="renumber",
+                    label="Renumber Extension",
+                    impact=f"Change extension for {len(conflicting_ids) - 1} of "
+                           f"{len(conflicting_ids)} conflicting lines",
+                ),
+                DecisionOption(
+                    id="virtual_line",
+                    label="Use Virtual Line",
+                    impact=f"Create virtual line(s) for {len(conflicting_ids) - 1} "
+                           f"conflicting appearances",
+                ),
+                DecisionOption(
+                    id="skip",
+                    label="Skip",
+                    impact=f"Leave {len(conflicting_ids)} lines unresolved — "
+                           f"manual intervention required",
+                ),
+            ]
+
+            decision = self._create_decision(
+                store=store,
+                decision_type=DecisionType.EXTENSION_CONFLICT,
+                severity=severity,
+                summary=(
+                    f"Extension {ext} used by {len(conflicting_ids)} lines "
+                    f"in location {loc_cid}"
+                ),
+                context=context,
+                options=options,
+                affected_objects=sorted(conflicting_ids),
+            )
+            decisions.append(decision)
+
+        return decisions
+
+    def fingerprint(self, decision_type: DecisionType, context: dict[str, Any]) -> str:
+        """Deterministic fingerprint from extension, location, and affected line IDs.
+
+        Includes:
+        - extension (the triggering condition)
+        - location_canonical_id (scope of the conflict)
+        - sorted canonical_ids of all conflicting lines (affected objects)
+
+        (from 07-idempotency-resumability.md lines 30-43)
+        """
+        conflicting_ids = sorted(
+            line.get("canonical_id", "")
+            for line in context.get("conflicting_lines", [])
+        )
+        return self._hash_fingerprint({
+            "type": decision_type.value,
+            "extension": context.get("extension"),
+            "location_canonical_id": context.get("location_canonical_id"),
+            "conflicting_line_ids": conflicting_ids,
+        })