wxcli 1.2.0__py3-none-any.whl

wxcli/migration/transform/analyzers/shared_line.py

@@ -0,0 +1,170 @@
+"""Shared line analyzer — finds DNs shared across multiple device owners.
+
+Detects directory numbers that appear on devices belonging to different users.
+These shared-line appearances require a migration decision because Webex Calling
+handles multi-user shared lines differently from CUCM (virtual lines, Webex
+shared lines, or call park + BLF).
+
+Decision ownership: ANALYZER-OWNED (no mapper produces SHARED_LINE_COMPLEX).
+
+(from 03-conflict-detection-engine.md, shared line 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 SharedLineAnalyzer(Analyzer):
+    """Finds DNs shared across multiple device owners.
+
+    CUCM allows a single DN to appear on multiple devices owned by different
+    users.  Webex Calling supports simple two-device shared lines natively,
+    but more complex arrangements (3+ devices, multiple owners) require
+    virtual lines, call park + BLF, or other workarounds.
+
+    Detection: query cross_refs for device_has_dn relationships, group by DN,
+    find DNs referenced by 2+ devices, then resolve unique owners.
+    """
+
+    name = "shared_lines"
+    decision_types = [DecisionType.SHARED_LINE_COMPLEX]
+
+    def analyze(self, store: MigrationStore) -> list[Decision]:
+        """Sweep all device-to-DN cross-refs, find DNs with multiple device owners."""
+        decisions: list[Decision] = []
+
+        # Step 1: Find DNs referenced by multiple devices via raw SQL
+        rows = store.conn.execute("""
+            SELECT cr.to_id AS dn_id, COUNT(DISTINCT cr.from_id) AS device_count
+            FROM cross_refs cr
+            WHERE cr.relationship = 'device_has_dn'
+            GROUP BY cr.to_id
+            HAVING COUNT(DISTINCT cr.from_id) > 1
+        """).fetchall()
+
+        if not rows:
+            return decisions
+
+        # Step 2: For each shared DN, gather details and resolve owners
+        for row in rows:
+            dn_id: str = row["dn_id"]
+            device_count: int = row["device_count"]
+
+            # Get DN data
+            dn_data = store.get_object(dn_id)
+            if dn_data is None:
+                continue
+
+            extension = dn_data.get("extension")
+            cucm_pattern = dn_data.get("cucm_pattern")
+            route_partition_name = dn_data.get("route_partition_name")
+
+            # Get all devices that reference this DN
+            device_refs = store.conn.execute(
+                "SELECT from_id FROM cross_refs WHERE to_id = ? AND relationship = 'device_has_dn'",
+                (dn_id,),
+            ).fetchall()
+            device_ids = [r["from_id"] for r in device_refs]
+
+            # Resolve unique owners from each device's data
+            owner_set: set[str] = set()
+            owner_ids: list[str] = []
+            for dev_id in device_ids:
+                dev_data = store.get_object(dev_id)
+                if dev_data is not None:
+                    owner = dev_data.get("owner_canonical_id")
+                    if owner and owner not in owner_set:
+                        owner_set.add(owner)
+                        owner_ids.append(owner)
+
+            # Only flag if there are multiple unique owners
+            if len(owner_ids) < 2:
+                continue
+
+            unique_owners = len(owner_ids)
+            severity = "HIGH" if unique_owners > 2 else "MEDIUM"
+
+            # Build options
+            dn_display = extension or cucm_pattern or dn_id
+
+            options = [
+                DecisionOption(
+                    id="virtual_line",
+                    label="Virtual Line",
+                    impact=f"1 virtual line + {device_count} line assignments",
+                ),
+            ]
+
+            if device_count <= 2:
+                options.append(
+                    DecisionOption(
+                        id="shared_line",
+                        label="Webex Shared Line",
+                        impact="Simple shared line between 2 devices",
+                    )
+                )
+
+            options.extend([
+                DecisionOption(
+                    id="call_park",
+                    label="Call Park + BLF",
+                    impact="Loses real-time shared state",
+                ),
+                DecisionOption(
+                    id="skip",
+                    label="Skip",
+                    impact="DN migrated only on primary owner's device",
+                ),
+            ])
+
+            context = {
+                "dn": dn_display,
+                "partition": route_partition_name,
+                "device_count": device_count,
+                "owner_ids": sorted(owner_ids),
+                "dn_canonical_id": dn_id,
+            }
+
+            affected_objects = [dn_id] + sorted(device_ids)
+
+            decision = self._create_decision(
+                store=store,
+                decision_type=DecisionType.SHARED_LINE_COMPLEX,
+                severity=severity,
+                summary=(
+                    f"DN {dn_display} shared across {device_count} devices "
+                    f"with {unique_owners} unique owners"
+                ),
+                context=context,
+                options=options,
+                affected_objects=affected_objects,
+            )
+            decisions.append(decision)
+
+        return decisions
+
+    def fingerprint(self, decision_type: DecisionType, context: dict[str, Any]) -> str:
+        """Deterministic fingerprint from DN, partition, owners, and device count.
+
+        Includes:
+        - dn (the shared extension or pattern)
+        - partition (route partition — scope of the DN)
+        - sorted owner_ids (all users who share this DN)
+        - device_count (number of devices — change invalidates resolution)
+
+        (from 07-idempotency-resumability.md lines 30-43)
+        """
+        return self._hash_fingerprint({
+            "type": decision_type.value,
+            "dn": context.get("dn"),
+            "partition": context.get("partition"),
+            "owner_ids": sorted(context.get("owner_ids", [])),
+            "device_count": context.get("device_count"),
+        })

wxcli/migration/transform/analyzers/voicemail_compatibility.py

@@ -0,0 +1,267 @@
+"""Voicemail compatibility analyzer for CUCM-to-Webex migration.
+
+Finds voicemail profiles with Unity Connection features that lack
+Webex Calling equivalents (fax-to-voicemail, non-standard message
+storage, complex transfer routing).
+
+VOICEMAIL_INCOMPATIBLE is a mapper-owned decision type — the
+voicemail_mapper already produces these during transform.  This
+analyzer backfills any profiles the mapper missed or that were
+added after initial mapping.
+
+(from 03-conflict-detection-engine.md, linter pattern)
+(from phase-06-analyzers.md, Decision Ownership Table — VOICEMAIL_INCOMPATIBLE 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
+
+
+# ---------------------------------------------------------------------------
+# Incompatibility detection helpers
+# ---------------------------------------------------------------------------
+
+def _has_fax_message(profile: dict[str, Any]) -> str | None:
+    """Return issue string if fax-to-voicemail is configured."""
+    fax = profile.get("fax_message")
+    if fax:
+        return "fax_message: Webex has no fax-to-voicemail"
+    return None
+
+
+def _has_nonstandard_storage(profile: dict[str, Any]) -> str | None:
+    """Return issue string if message_storage uses non-standard settings."""
+    storage = profile.get("message_storage")
+    if storage is None:
+        return None
+    if isinstance(storage, str):
+        normalized = storage.strip().lower()
+        if normalized in ("", "standard", "default", "mailbox"):
+            return None
+        return f"message_storage '{storage}': non-standard storage not supported in Webex"
+    if isinstance(storage, dict):
+        # Dict-form storage — check for MWI-only or external indicators
+        storage_type = storage.get("type", "").lower()
+        if storage_type in ("mwi_only", "mwi-only", "external"):
+            return f"message_storage type '{storage_type}': not supported in Webex"
+        # Non-empty dict with unexpected keys suggests custom config
+        if storage and storage_type not in ("", "standard", "default", "mailbox"):
+            return f"message_storage type '{storage_type}': non-standard storage not supported in Webex"
+    return None
+
+
+def _has_complex_transfer(profile: dict[str, Any]) -> str | None:
+    """Return issue string if transfer_to_number has complex routing."""
+    transfer = profile.get("transfer_to_number")
+    if transfer is None:
+        return None
+    if isinstance(transfer, str) and transfer.strip():
+        # Simple transfer number — this maps to Webex forwarding, minor gap
+        return None
+    if isinstance(transfer, dict):
+        # Dict-form transfer implies complex routing rules
+        rules = transfer.get("rules") or transfer.get("conditions")
+        if rules:
+            return "transfer_to_number: complex routing rules cannot map to Webex"
+        # Has a transfer config dict but no complex rules — check for non-empty
+        transfer_type = transfer.get("type", "")
+        if transfer_type and transfer_type.lower() not in ("", "simple", "direct"):
+            return f"transfer_to_number type '{transfer_type}': complex transfer not supported in Webex"
+    return None
+
+
+def _check_warnings(profile: dict[str, Any]) -> list[str]:
+    """Extract voicemail-related warnings from the object's warnings list."""
+    warnings = profile.get("warnings") or []
+    issues: list[str] = []
+    for w in warnings:
+        if not isinstance(w, str):
+            continue
+        w_lower = w.lower()
+        if any(kw in w_lower for kw in (
+            "voicemail", "unity", "fax", "message storage",
+            "not supported", "incompatible", "mwi",
+        )):
+            issues.append(f"warning: {w}")
+    return issues
+
+
+# Severity assignment: fax and complex transfer are MEDIUM;
+# non-standard storage and warning-only issues are MEDIUM;
+# simple warnings are LOW.
+_HIGH_KEYWORDS = frozenset()  # nothing is HIGH for voicemail incompatibilities
+_MEDIUM_KEYWORDS = frozenset((
+    "fax_message", "message_storage", "transfer_to_number",
+))
+
+
+class VoicemailCompatibilityAnalyzer(Analyzer):
+    """Detects voicemail profiles with Unity Connection features that
+    lack Webex Calling equivalents.
+
+    Checks each voicemail_profile object for:
+    - fax_message configured (Webex has no fax-to-voicemail)
+    - message_storage with MWI-only or external storage
+    - transfer_to_number with complex routing rules
+    - Warnings on the object indicating incompatibility
+
+    Skips profiles already covered by voicemail_mapper decisions.
+
+    (from 03-conflict-detection-engine.md, voicemail compatibility linter)
+    """
+
+    name = "voicemail_compatibility"
+    decision_types = [DecisionType.VOICEMAIL_INCOMPATIBLE]
+    depends_on: list[str] = []
+
+    def analyze(self, store: MigrationStore) -> list[Decision]:
+        """Sweep voicemail profiles for incompatible features."""
+        # Existing mapper-produced decisions indexed by canonical_id
+        existing = self._get_existing_decisions_for_type(
+            store, DecisionType.VOICEMAIL_INCOMPATIBLE
+        )
+
+        decisions: list[Decision] = []
+        profiles = store.get_objects("voicemail_profile")
+
+        for profile in profiles:
+            canonical_id = profile.get("canonical_id", "")
+
+            # Skip if mapper already produced a decision for this profile
+            if canonical_id in existing:
+                continue
+
+            incompatible_features = self._detect_incompatibilities(profile)
+            if not incompatible_features:
+                continue
+
+            severity = self._determine_severity(incompatible_features)
+            profile_name = (
+                profile.get("cucm_voicemail_profile_name")
+                or profile.get("name")
+                or canonical_id
+            )
+            user_canonical_id = profile.get("user_canonical_id", "")
+
+            summary = (
+                f"Voicemail profile '{profile_name}' has {len(incompatible_features)} "
+                f"feature(s) incompatible with Webex: "
+                f"{', '.join(self._feature_names(incompatible_features))}"
+            )
+
+            context = {
+                "canonical_id": canonical_id,
+                "profile_name": profile_name,
+                "user_canonical_id": user_canonical_id,
+                "incompatible_features": incompatible_features,
+            }
+
+            options = [
+                DecisionOption(
+                    id="accept",
+                    label="Accept fidelity loss",
+                    impact=(
+                        f"Voicemail profile '{profile_name}' migrated without "
+                        f"{', '.join(self._feature_names(incompatible_features))}"
+                    ),
+                ),
+                DecisionOption(
+                    id="manual",
+                    label="Configure manually post-migration",
+                    impact=(
+                        f"Voicemail profile '{profile_name}' flagged for manual "
+                        f"post-migration configuration"
+                    ),
+                ),
+                DecisionOption(
+                    id="skip",
+                    label="Skip this profile",
+                    impact=f"Voicemail profile '{profile_name}' excluded from migration",
+                ),
+            ]
+
+            affected = [canonical_id]
+            if user_canonical_id:
+                affected.append(user_canonical_id)
+
+            decision = self._create_decision(
+                store=store,
+                decision_type=DecisionType.VOICEMAIL_INCOMPATIBLE,
+                severity=severity,
+                summary=summary,
+                context=context,
+                options=options,
+                affected_objects=affected,
+            )
+            decisions.append(decision)
+
+        return decisions
+
+    def fingerprint(self, decision_type: DecisionType, context: dict[str, Any]) -> str:
+        """Deterministic fingerprint from canonical_id + sorted incompatible feature names."""
+        features = context.get("incompatible_features", [])
+        return self._hash_fingerprint({
+            "type": decision_type.value,
+            "canonical_id": context.get("canonical_id", ""),
+            "incompatible_features": sorted(self._feature_names(features)),
+        })
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _detect_incompatibilities(profile: dict[str, Any]) -> list[str]:
+        """Return list of issue description strings for all detected incompatibilities."""
+        issues: list[str] = []
+
+        fax_issue = _has_fax_message(profile)
+        if fax_issue:
+            issues.append(fax_issue)
+
+        storage_issue = _has_nonstandard_storage(profile)
+        if storage_issue:
+            issues.append(storage_issue)
+
+        transfer_issue = _has_complex_transfer(profile)
+        if transfer_issue:
+            issues.append(transfer_issue)
+
+        warning_issues = _check_warnings(profile)
+        issues.extend(warning_issues)
+
+        return issues
+
+    @staticmethod
+    def _feature_names(issues: list[str]) -> list[str]:
+        """Extract short feature names from issue description strings.
+
+        E.g., "fax_message: Webex has no fax-to-voicemail" -> "fax_message"
+        """
+        names: list[str] = []
+        for issue in issues:
+            if ":" in issue:
+                name = issue.split(":")[0].strip()
+            else:
+                name = issue[:40]
+            names.append(name)
+        return names
+
+    @staticmethod
+    def _determine_severity(issues: list[str]) -> str:
+        """Determine decision severity based on the incompatible features found.
+
+        MEDIUM for feature-level incompatibilities (fax, storage, transfer).
+        LOW for warning-only issues.
+        """
+        for issue in issues:
+            prefix = issue.split(":")[0].strip() if ":" in issue else ""
+            if prefix in _MEDIUM_KEYWORDS:
+                return "MEDIUM"
+        # All issues are warning-based
+        return "LOW"

wxcli/migration/transform/analyzers/workspace_license.py

@@ -0,0 +1,212 @@
+"""Workspace license tier analyzer for CUCM-to-Webex migration.
+
+Determines whether each workspace needs a Workspace or Professional Workspace
+Webex Calling license based on its configured features.
+
+WORKSPACE_LICENSE_TIER is a mapper-owned decision type — the
+workspace_mapper may already produce these during transform.
+This analyzer catches workspaces the mapper didn't cover and
+workspaces whose feature profile suggests a tier mismatch.
+
+(from 03-conflict-detection-engine.md, linter pattern)
+(from phase-06-analyzers.md, Decision Ownership Table — WORKSPACE_LICENSE_TIER 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
+
+
+# ---------------------------------------------------------------------------
+# Feature indicators that suggest Professional Workspace license is needed
+# ---------------------------------------------------------------------------
+# Each entry: (field_name, check_fn, feature_label)
+# check_fn receives the field value and returns True if the feature IS present.
+
+def _has_value(val: Any) -> bool:
+    """True if the value is not None and not empty/falsy."""
+    if val is None:
+        return False
+    if isinstance(val, (str, list, dict)) and not val:
+        return False
+    return True
+
+
+def _is_hotdesking_on(val: Any) -> bool:
+    return isinstance(val, str) and val.lower() == "on"
+
+
+_PROFESSIONAL_INDICATORS: list[tuple[str, Any, str]] = [
+    ("hotdesking_status", _is_hotdesking_on, "hot-desking enabled"),
+    ("phone_number", _has_value, "DID phone number assigned"),
+]
+
+# Features detected via cross-references (relationship, label)
+_XREF_INDICATORS: list[tuple[str, str]] = [
+    ("workspace_has_voicemail", "voicemail configured"),
+    ("workspace_has_call_forwarding", "call forwarding configured"),
+    ("workspace_has_shared_line", "shared line appearance"),
+]
+
+
+class WorkspaceLicenseAnalyzer(Analyzer):
+    """Determines Workspace vs Professional Workspace license for workspaces.
+
+    Webex Calling workspaces can be provisioned with Workspace or
+    Professional Workspace licenses. Several features require Professional Workspace:
+    - Hot-desking
+    - DID phone numbers
+    - Voicemail
+    - Call forwarding
+    - Shared line appearances
+    - Most /telephony/config/workspaces/ settings
+
+    The workspace_mapper sets ``license_tier`` during transform when the
+    answer is obvious.  This analyzer catches workspaces where:
+    1. The mapper didn't set a tier (license_tier is None)
+    2. The workspace has feature indicators that create ambiguity
+
+    (from docs/reference/devices-workspaces.md, Workspace vs Professional Workspace)
+    """
+
+    name = "workspace_license"
+    decision_types = [DecisionType.WORKSPACE_LICENSE_TIER]
+
+    def analyze(self, store: MigrationStore) -> list[Decision]:
+        """Sweep workspaces for undecided or ambiguous license tiers."""
+        # Existing mapper-produced decisions indexed by canonical_id
+        existing = self._get_existing_decisions_for_type(
+            store, DecisionType.WORKSPACE_LICENSE_TIER
+        )
+
+        decisions: list[Decision] = []
+        workspaces = store.get_objects("workspace")
+
+        for ws in workspaces:
+            canonical_id = ws.get("canonical_id", "")
+
+            # Skip workspaces the mapper already produced a decision for
+            if canonical_id in existing:
+                continue
+
+            license_tier = ws.get("license_tier")
+            features_detected = self._detect_features(ws, store, canonical_id)
+
+            # Case 1: mapper already set a definite tier and no conflicting features
+            if license_tier is not None and not features_detected:
+                continue
+
+            # Case 2: tier is set but features suggest it might be wrong
+            # (e.g., mapper said Workspace but workspace has voicemail)
+            if license_tier == "Workspace" and features_detected:
+                summary = (
+                    f"Workspace '{ws.get('display_name', canonical_id)}' set to Workspace "
+                    f"but has Professional Workspace features: {', '.join(features_detected)}"
+                )
+            # Case 3: no tier set at all
+            elif license_tier is None:
+                if features_detected:
+                    summary = (
+                        f"Workspace '{ws.get('display_name', canonical_id)}' needs license "
+                        f"tier — detected features: {', '.join(features_detected)}"
+                    )
+                else:
+                    summary = (
+                        f"Workspace '{ws.get('display_name', canonical_id)}' needs license "
+                        f"tier assignment (no feature indicators detected)"
+                    )
+            else:
+                # Professional Workspace tier set, features present — consistent, no decision needed
+                continue
+
+            context = {
+                "canonical_id": canonical_id,
+                "display_name": ws.get("display_name"),
+                "license_tier": license_tier,
+                "features_detected": features_detected,
+            }
+
+            options = [
+                DecisionOption(
+                    id="workspace",
+                    label="Workspace",
+                    impact="Workspace license; limited to basic calling features",
+                ),
+                DecisionOption(
+                    id="professional",
+                    label="Professional Workspace",
+                    impact="Professional Workspace license; full calling features including voicemail, forwarding, hot-desking",
+                ),
+                DecisionOption(
+                    id="skip",
+                    label="Skip this workspace",
+                    impact="1 workspace excluded from migration",
+                ),
+            ]
+
+            decision = self._create_decision(
+                store=store,
+                decision_type=DecisionType.WORKSPACE_LICENSE_TIER,
+                severity="MEDIUM",
+                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 + license tier + detected features.
+
+        Includes features_detected so that discovering new Professional Workspace-tier
+        features invalidates a previous "Workspace" resolution.
+        (from 07-idempotency-resumability.md: include data whose change would
+        invalidate a previous resolution)
+        """
+        return self._hash_fingerprint({
+            "type": decision_type.value,
+            "canonical_id": context.get("canonical_id", ""),
+            "license_tier": context.get("license_tier"),
+            "features_detected": sorted(context.get("features_detected", [])),
+        })
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _detect_features(
+        ws: dict[str, Any],
+        store: MigrationStore,
+        canonical_id: str,
+    ) -> list[str]:
+        """Detect features that suggest Professional Workspace license is needed.
+
+        Checks both workspace data fields and cross-references to
+        related objects (voicemail profiles, call forwarding, shared lines).
+        """
+        features: list[str] = []
+
+        # Check data fields
+        for field_name, check_fn, label in _PROFESSIONAL_INDICATORS:
+            if check_fn(ws.get(field_name)):
+                features.append(label)
+
+        # Check multiple line appearances (>1 line suggests shared/complex config)
+        line_refs = store.find_cross_refs(canonical_id, "workspace_has_line")
+        if len(line_refs) > 1:
+            features.append(f"multiple lines ({len(line_refs)})")
+
+        # Check cross-reference indicators
+        for relationship, label in _XREF_INDICATORS:
+            refs = store.find_cross_refs(canonical_id, relationship)
+            if refs:
+                features.append(label)
+
+        return features