wxcli 1.2.0__py3-none-any.whl

wxcli/migration/transform/analyzers/missing_data.py

@@ -0,0 +1,300 @@
+"""Missing data analyzer for CUCM-to-Webex migration.
+
+Sweeps the inventory for objects with null/empty required fields
+and produces MISSING_DATA decisions so users can supply the data
+or choose to skip the object.
+
+MISSING_DATA is a mapper-owned decision type — multiple mappers
+can produce these decisions.  This analyzer checks for existing
+mapper decisions before creating new ones.
+
+(from 03-conflict-detection-engine.md, linter pattern)
+(from phase-06-analyzers.md, Decision Ownership Table — MISSING_DATA 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
+
+
+# ---------------------------------------------------------------------------
+# Required-field definitions per object type
+# ---------------------------------------------------------------------------
+
+# Each entry: (field_name, check_fn, severity, description)
+# check_fn receives the field value and returns True if the value is MISSING.
+
+def _is_empty_list(val: Any) -> bool:
+    return val is None or (isinstance(val, list) and len(val) == 0)
+
+
+def _is_none(val: Any) -> bool:
+    return val is None
+
+
+def _is_none_or_blank(val: Any) -> bool:
+    return val is None or (isinstance(val, str) and val.strip() == "")
+
+
+def _get_nested(obj: dict, dotted_key: str) -> Any:
+    """Retrieve a value from a dict using dot-notation (e.g., 'address.country')."""
+    parts = dotted_key.split(".")
+    val = obj
+    for p in parts:
+        if isinstance(val, dict):
+            val = val.get(p)
+        else:
+            return None
+    return val
+
+
+_REQUIRED_FIELDS: dict[str, list[tuple[str, Any, str, str]]] = {
+    "user": [
+        ("emails", _is_empty_list, "HIGH", "Email address required for Webex identity"),
+        ("first_name", _is_none_or_blank, "MEDIUM", "First or last name required"),
+        ("last_name", _is_none_or_blank, "MEDIUM", "First or last name required"),
+        # Fix 5: location_id required for Webex Calling provisioning
+        ("location_id", _is_none_or_blank, "HIGH", "Location assignment required for Webex Calling"),
+    ],
+    "device": [
+        ("mac", _is_none_or_blank, "MEDIUM", "MAC address required for device migration"),
+        ("owner_canonical_id", _is_none_or_blank, "MEDIUM", "Device owner required for assignment"),
+    ],
+    "trunk": [
+        ("address", _is_none_or_blank, "MEDIUM", "FQDN/SRV address required for trunk registration"),
+        # password NOT checked — Webex Calling trunks use certificate-based TLS,
+        # not SIP password auth. CUCM never exposes passwords via AXL anyway.
+    ],
+    "location": [
+        ("name", _is_none_or_blank, "MEDIUM", "Location name required"),
+        # Fix 4: Address fields — E911 compliance
+        ("address.country", _is_none_or_blank, "HIGH", "Country required for E911 compliance"),
+        ("address.address1", _is_none_or_blank, "HIGH", "Street address required for E911 compliance"),
+        ("address.city", _is_none_or_blank, "HIGH", "City required for E911 compliance"),
+        ("address.state", _is_none_or_blank, "HIGH", "State/province required for E911 compliance"),
+        ("address.postal_code", _is_none_or_blank, "MEDIUM", "Postal code required for full address"),
+    ],
+    # Fix 6: Translation pattern required fields
+    "translation_pattern": [
+        ("matching_pattern", _is_none_or_blank, "HIGH", "Pattern required for translation"),
+        ("name", _is_none_or_blank, "MEDIUM", "Name required for identification"),
+    ],
+    # Fix 11: Route group required fields
+    "route_group": [
+        ("local_gateways", _is_empty_list, "HIGH", "At least one gateway required"),
+    ],
+    # Lines handled separately in _check_lines() — extension is only
+    # required for EXTENSION-classified lines (special logic).
+}
+
+
+class MissingDataAnalyzer(Analyzer):
+    """Finds objects where required fields are null or empty.
+
+    For users: checks emails (HIGH — blocks identity provisioning), first_name/last_name.
+    For users with name fields: only flags if BOTH first_name AND last_name are missing
+    (having either one is acceptable).
+
+    For devices: checks mac and owner_canonical_id.
+    For trunks: checks address and password.
+    For locations: checks name.
+    For lines: checks extension (only when classification == EXTENSION).
+
+    (from 03-conflict-detection-engine.md, MissingDataAnalyzer)
+    """
+
+    name = "missing_data"
+    decision_types = [DecisionType.MISSING_DATA]
+
+    def analyze(self, store: MigrationStore) -> list[Decision]:
+        """Sweep all object types for missing required fields."""
+        # Collect existing mapper-produced MISSING_DATA decisions so we skip
+        # objects that already have one.
+        existing = self._get_existing_decisions_for_type(store, DecisionType.MISSING_DATA)
+
+        decisions: list[Decision] = []
+
+        for object_type, field_defs in _REQUIRED_FIELDS.items():
+            objects = store.get_objects(object_type)
+            for obj in objects:
+                canonical_id = obj.get("canonical_id", "")
+
+                # Skip if mapper already produced a MISSING_DATA decision
+                if canonical_id in existing:
+                    continue
+
+                # Webex App devices (Jabber, CSF, Dual Mode, IP Communicator)
+                # and infrastructure devices (CTI, CER, gateways) don't need
+                # a MAC address or owner — they aren't migrated as Webex devices.
+                if object_type == "device" and obj.get("compatibility_tier") in ("webex_app", "infrastructure", "dect"):
+                    continue  # Skip all missing-data checks for non-migratable devices
+                else:
+                    active_fields = field_defs
+
+                missing = self._check_object(object_type, obj, active_fields)
+                if not missing:
+                    continue
+
+                # Determine severity — take the highest among missing fields
+                severity = self._highest_severity(missing)
+                missing_names = sorted([m[0] for m in missing])
+
+                summary = (
+                    f"{object_type} '{canonical_id}' missing required fields: "
+                    f"{', '.join(missing_names)}"
+                )
+
+                context = {
+                    "object_type": object_type,
+                    "canonical_id": canonical_id,
+                    "missing_fields": missing_names,
+                }
+
+                options = [
+                    DecisionOption(
+                        id="provide_data",
+                        label="Provide missing data",
+                        impact=f"User will supply {len(missing_names)} missing field(s)",
+                    ),
+                    DecisionOption(
+                        id="skip",
+                        label="Skip this object",
+                        impact=f"1 {object_type} excluded from migration",
+                    ),
+                    DecisionOption(
+                        id="manual",
+                        label="Handle manually post-migration",
+                        impact=f"Object migrated without {', '.join(missing_names)}; fix manually",
+                    ),
+                ]
+
+                decision = self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.MISSING_DATA,
+                    severity=severity,
+                    summary=summary,
+                    context=context,
+                    options=options,
+                    affected_objects=[canonical_id],
+                )
+                decisions.append(decision)
+
+        # Handle lines separately (extension-only check for EXTENSION lines)
+        decisions.extend(self._check_lines(store, existing))
+
+        return decisions
+
+    def fingerprint(self, decision_type: DecisionType, context: dict[str, Any]) -> str:
+        """Deterministic fingerprint from canonical_id + sorted missing fields."""
+        return self._hash_fingerprint({
+            "type": decision_type.value,
+            "canonical_id": context.get("canonical_id", ""),
+            "missing_fields": sorted(context.get("missing_fields", [])),
+        })
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _check_object(
+        object_type: str,
+        obj: dict[str, Any],
+        field_defs: list[tuple[str, Any, str, str]],
+    ) -> list[tuple[str, str, str]]:
+        """Return list of (field_name, severity, description) for missing fields.
+
+        Special case for user: first_name/last_name only flagged when BOTH missing.
+        Supports dot-notation for nested fields (e.g., 'address.country').
+        """
+        missing: list[tuple[str, str, str]] = []
+
+        if object_type == "user":
+            # Email and location_id are always required
+            for field_name, check_fn, severity, desc in field_defs:
+                if field_name in ("emails", "location_id"):
+                    val = _get_nested(obj, field_name) if "." in field_name else obj.get(field_name)
+                    if check_fn(val):
+                        missing.append((field_name, severity, desc))
+            # Name: flag only if both first_name AND last_name are missing
+            first = obj.get("first_name")
+            last = obj.get("last_name")
+            if _is_none_or_blank(first) and _is_none_or_blank(last):
+                missing.append(("first_name/last_name", "MEDIUM", "First or last name required"))
+        else:
+            for field_name, check_fn, severity, desc in field_defs:
+                # Support dot-notation for nested fields (Fix 4)
+                val = _get_nested(obj, field_name) if "." in field_name else obj.get(field_name)
+                if check_fn(val):
+                    missing.append((field_name, severity, desc))
+
+        return missing
+
+    def _check_lines(
+        self,
+        store: MigrationStore,
+        existing: dict[str, dict[str, Any]],
+    ) -> list[Decision]:
+        """Check lines: extension is required only for EXTENSION-classified lines."""
+        decisions: list[Decision] = []
+        lines = store.get_objects("line")
+
+        for line in lines:
+            canonical_id = line.get("canonical_id", "")
+            if canonical_id in existing:
+                continue
+
+            classification = line.get("classification")
+            extension = line.get("extension")
+
+            # Only flag missing extension for EXTENSION-classified lines
+            if classification == "EXTENSION" and _is_none_or_blank(extension):
+                context = {
+                    "object_type": "line",
+                    "canonical_id": canonical_id,
+                    "missing_fields": ["extension"],
+                }
+                decision = self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.MISSING_DATA,
+                    severity="MEDIUM",
+                    summary=(
+                        f"line '{canonical_id}' classified as EXTENSION but extension is empty"
+                    ),
+                    context=context,
+                    options=[
+                        DecisionOption(
+                            id="provide_data",
+                            label="Provide extension number",
+                            impact="User will supply the extension value",
+                        ),
+                        DecisionOption(
+                            id="skip",
+                            label="Skip this line",
+                            impact="1 line excluded from migration",
+                        ),
+                        DecisionOption(
+                            id="manual",
+                            label="Handle manually post-migration",
+                            impact="Line migrated without extension; fix manually",
+                        ),
+                    ],
+                    affected_objects=[canonical_id],
+                )
+                decisions.append(decision)
+
+        return decisions
+
+    @staticmethod
+    def _highest_severity(missing: list[tuple[str, str, str]]) -> str:
+        """Return the highest severity among the missing fields."""
+        order = {"HIGH": 3, "MEDIUM": 2, "LOW": 1}
+        best = "LOW"
+        for _, sev, _ in missing:
+            if order.get(sev, 0) > order.get(best, 0):
+                best = sev
+        return best

wxcli/migration/transform/analyzers/selective_call_handling.py

@@ -0,0 +1,394 @@
+"""Selective call handling analyzer for CUCM-to-Webex migration.
+
+Detects CUCM CSS/partition patterns that imply per-caller routing differences
+and produces FEATURE_APPROXIMATION advisory decisions recommending Webex
+selective call handling features (Selective Forward / Accept / Reject /
+Priority Alert).
+
+Three heuristics:
+1. Multi-partition DN — same DN in 2+ partitions reachable via different
+   user CSSes (internal vs external routing split).
+2. Low-membership partition — partition with few DNs that appears in only
+   a subset of CSSes (VIP/priority bypass pattern).
+3. Naming convention — partition name contains VIP/executive/priority
+   keywords (weak signal, only LOW severity unless paired with structural
+   signal).
+
+This analyzer reuses DecisionType.FEATURE_APPROXIMATION with a distinguishing
+context key `selective_call_handling_pattern`. The recommendation rule and
+report renderer key off this context key.
+
+Spec: docs/superpowers/specs/2026-04-10-selective-call-forwarding.md
+"""
+
+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
+
+
+_VIP_KEYWORDS = (
+    "vip",
+    "executive",
+    "exec",
+    "priority",
+    "direct",
+    "bypass",
+    "afterhours",
+    "after_hours",
+    "after-hours",
+    "emergency",
+)
+
+
+class SelectiveCallHandlingAnalyzer(Analyzer):
+    """Detects CSS/partition patterns suggesting selective call handling.
+
+    See module docstring for the three heuristics. Produces
+    FEATURE_APPROXIMATION decisions with context key
+    `selective_call_handling_pattern` set to one of:
+        - "multi_partition_dn"
+        - "low_membership_partition"
+        - "naming_convention"
+    """
+
+    name = "selective_call_handling"
+    decision_types = [DecisionType.FEATURE_APPROXIMATION]
+    # Run after css_routing so CSS decomposition decisions are merged first.
+    depends_on = ["css_routing"]
+
+    def analyze(self, store: MigrationStore) -> list[Decision]:
+        decisions: list[Decision] = []
+        decisions.extend(self._heuristic_multi_partition_dn(store))
+        decisions.extend(self._heuristic_low_membership_partition(store))
+        decisions.extend(self._heuristic_naming_convention(store, decisions))
+        return decisions
+
+    def fingerprint(
+        self, decision_type: DecisionType, context: dict[str, Any]
+    ) -> str:
+        """Deterministic fingerprint from pattern type + natural keys."""
+        return self._hash_fingerprint({
+            "type": decision_type.value,
+            "pattern": context.get("selective_call_handling_pattern", ""),
+            "primary_key": context.get("primary_key", ""),
+            "partitions": sorted(context.get("partitions", [])),
+            "user": context.get("user_canonical_id", ""),
+        })
+
+    # ------------------------------------------------------------------
+    # Heuristics — implemented in later tasks
+    # ------------------------------------------------------------------
+
+    def _heuristic_multi_partition_dn(
+        self, store: MigrationStore
+    ) -> list[Decision]:
+        """Find DNs in 2+ partitions reachable via different user CSSes."""
+        # Build {dn_number: {partition_name: dn_canonical_id}} from cross_refs.
+        # The dn_canonical_id form is "dn:{number}:{partition}".
+        rows = store.conn.execute(
+            "SELECT from_id, to_id FROM cross_refs WHERE relationship = 'dn_in_partition'"
+        ).fetchall()
+        dn_to_partitions: dict[str, dict[str, str]] = defaultdict(dict)
+        for row in rows:
+            dn_canonical_id = row["from_id"]
+            partition_canonical_id = row["to_id"]
+            # Extract the dn number from "dn:{number}:{partition}"
+            parts = dn_canonical_id.split(":", 2)
+            if len(parts) < 3:
+                continue
+            dn_number = parts[1]
+            partition_name = (
+                partition_canonical_id.split(":", 1)[1]
+                if ":" in partition_canonical_id
+                else partition_canonical_id
+            )
+            dn_to_partitions[dn_number][partition_name] = dn_canonical_id
+
+        # Map user_id → set of CSS canonical_ids and CSS → set of partition_ids
+        user_csses = self._build_user_css_index(store)
+        css_partitions = self._build_css_partition_index(store)
+        # Map dn canonical_id → owner user canonical_id (from user_has_primary_dn)
+        owner_rows = store.conn.execute(
+            "SELECT from_id, to_id FROM cross_refs WHERE relationship = 'user_has_primary_dn'"
+        ).fetchall()
+        dn_owner: dict[str, str] = {row["to_id"]: row["from_id"] for row in owner_rows}
+
+        decisions: list[Decision] = []
+        for dn_number, partition_map in sorted(dn_to_partitions.items()):
+            if len(partition_map) < 2:
+                continue
+
+            # Multi-site filter (mitigation 8a):
+            # Get owners across all partition variants for this DN number.
+            owner_ids: set[str] = set()
+            for dn_cid in partition_map.values():
+                owner = dn_owner.get(dn_cid)
+                if owner:
+                    owner_ids.add(owner)
+            owner_locations = self._owner_locations(store, owner_ids)
+            if len(owner_locations) > 1:
+                # Multi-site routing pattern, not selective call handling.
+                continue
+
+            # Determine severity: MEDIUM if owning user's CSSes have
+            # different scopes (different partition sets).
+            primary_owner = next(iter(owner_ids), "")
+            scopes = self._user_css_scopes(primary_owner, user_csses, css_partitions)
+            severity = "MEDIUM" if self._scopes_differ(scopes) else "LOW"
+
+            partitions_sorted = sorted(partition_map.keys())
+            context = {
+                "selective_call_handling_pattern": "multi_partition_dn",
+                "primary_key": dn_number,
+                "dn_number": dn_number,
+                "partitions": partitions_sorted,
+                "user_canonical_id": primary_owner,
+                "recommended_webex_feature": "Selective Forward",
+                "confidence": "HIGH" if severity == "MEDIUM" else "LOW",
+            }
+            options = self._build_options("Selective Forward")
+            summary = (
+                f"DN {dn_number} appears in {len(partitions_sorted)} partitions "
+                f"({', '.join(partitions_sorted)}); CUCM caller-specific routing "
+                f"pattern detected"
+            )
+            decisions.append(
+                self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.FEATURE_APPROXIMATION,
+                    severity=severity,
+                    summary=summary,
+                    context=context,
+                    options=options,
+                    affected_objects=[primary_owner] if primary_owner else [],
+                )
+            )
+        return decisions
+
+    # ------------------------------------------------------------------
+    # Shared helpers
+    # ------------------------------------------------------------------
+
+    def _build_user_css_index(
+        self, store: MigrationStore
+    ) -> dict[str, set[str]]:
+        rows = store.conn.execute(
+            "SELECT from_id, to_id FROM cross_refs WHERE relationship = 'user_has_css'"
+        ).fetchall()
+        index: dict[str, set[str]] = defaultdict(set)
+        for row in rows:
+            index[row["from_id"]].add(row["to_id"])
+        return index
+
+    def _build_css_partition_index(
+        self, store: MigrationStore
+    ) -> dict[str, set[str]]:
+        rows = store.conn.execute(
+            "SELECT from_id, to_id FROM cross_refs WHERE relationship = 'css_contains_partition'"
+        ).fetchall()
+        index: dict[str, set[str]] = defaultdict(set)
+        for row in rows:
+            index[row["from_id"]].add(row["to_id"])
+        return index
+
+    def _owner_locations(
+        self, store: MigrationStore, owner_ids: set[str]
+    ) -> set[str]:
+        locations: set[str] = set()
+        for owner_id in owner_ids:
+            obj = store.get_object(owner_id)
+            if obj is None:
+                continue
+            loc = obj.get("location_id")
+            if loc:
+                locations.add(loc)
+        return locations
+
+    def _user_css_scopes(
+        self,
+        user_id: str,
+        user_csses: dict[str, set[str]],
+        css_partitions: dict[str, set[str]],
+    ) -> list[set[str]]:
+        return [
+            css_partitions.get(css_id, set())
+            for css_id in user_csses.get(user_id, set())
+        ]
+
+    @staticmethod
+    def _scopes_differ(scopes: list[set[str]]) -> bool:
+        if len(scopes) < 2:
+            return False
+        # Any pair with non-empty symmetric difference → scopes differ.
+        for i in range(len(scopes)):
+            for j in range(i + 1, len(scopes)):
+                if scopes[i] ^ scopes[j]:
+                    return True
+        return False
+
+    @staticmethod
+    def _build_options(recommended_feature: str) -> list[DecisionOption]:
+        return [
+            DecisionOption(
+                id="accept",
+                label=f"Configure {recommended_feature} post-migration",
+                impact=(
+                    f"Operator manually configures Webex {recommended_feature} "
+                    f"to preserve CUCM caller-specific routing behavior"
+                ),
+            ),
+            DecisionOption(
+                id="skip",
+                label="Skip — accept loss of caller-specific routing",
+                impact=(
+                    "Per-caller routing differences are not preserved; "
+                    "callers reach the user via standard Webex routing"
+                ),
+            ),
+        ]
+
+    def _heuristic_low_membership_partition(
+        self, store: MigrationStore
+    ) -> list[Decision]:
+        """Find partitions with few DNs that appear in only a subset of CSSes."""
+        partitions = store.get_objects("partition")
+        if not partitions:
+            return []
+        css_partitions = self._build_css_partition_index(store)
+        # total_css_count must reflect all CSSes in the store (not just those
+        # that appear as keys in the cross_ref index — a CSS with no partitions
+        # assigned still counts toward the "universe" of CSSes).
+        total_css_count = len(store.get_objects("css"))
+        if total_css_count == 0:
+            return []
+
+        # Build reverse: partition_id → set of CSS canonical_ids that contain it
+        partition_in_css: dict[str, set[str]] = defaultdict(set)
+        for css_id, pt_ids in css_partitions.items():
+            for pt_id in pt_ids:
+                partition_in_css[pt_id].add(css_id)
+
+        decisions: list[Decision] = []
+        for pt in partitions:
+            pt_id = pt.get("canonical_id", "")
+            if not pt_id:
+                continue
+            dn_refs = store.find_cross_refs(pt_id, "partition_has_pattern")
+            dn_count = len(dn_refs)
+            if dn_count == 0 or dn_count > 10:
+                continue
+
+            css_count = len(partition_in_css.get(pt_id, set()))
+            # Universal partition or not in a strict minority of CSSes → not selective.
+            if css_count == 0 or css_count >= total_css_count * 0.5:
+                continue
+
+            partition_name = (
+                pt.get("pre_migration_state", {}).get("partition_name")
+                or pt_id.split(":", 1)[-1]
+            )
+
+            context = {
+                "selective_call_handling_pattern": "low_membership_partition",
+                "primary_key": partition_name,
+                "partitions": [partition_name],
+                "dn_count": dn_count,
+                "css_count": css_count,
+                "total_css_count": total_css_count,
+                "recommended_webex_feature": "Selective Accept",
+                "confidence": "HIGH",
+            }
+            options = self._build_options("Selective Accept")
+            summary = (
+                f"Partition '{partition_name}' has {dn_count} DN(s) and is "
+                f"reachable via only {css_count}/{total_css_count} CSSes "
+                f"(VIP/priority bypass pattern)"
+            )
+            decisions.append(
+                self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.FEATURE_APPROXIMATION,
+                    severity="MEDIUM",
+                    summary=summary,
+                    context=context,
+                    options=options,
+                    affected_objects=[pt_id],
+                )
+            )
+        return decisions
+
+    def _heuristic_naming_convention(
+        self,
+        store: MigrationStore,
+        existing_decisions: list[Decision],
+    ) -> list[Decision]:
+        """Flag VIP/executive-named partitions not already covered structurally."""
+        partitions = store.get_objects("partition")
+        if not partitions:
+            return []
+
+        # Set of partition canonical_ids already covered by a structural heuristic
+        covered: set[str] = set()
+        for dec in existing_decisions:
+            for obj_id in dec.affected_objects:
+                if obj_id.startswith("partition:"):
+                    covered.add(obj_id)
+
+        decisions: list[Decision] = []
+        for pt in partitions:
+            pt_id = pt.get("canonical_id", "")
+            if pt_id in covered:
+                continue
+            partition_name = (
+                pt.get("pre_migration_state", {}).get("partition_name")
+                or pt_id.split(":", 1)[-1]
+            )
+            if not self._matches_vip_keyword(partition_name):
+                continue
+
+            context = {
+                "selective_call_handling_pattern": "naming_convention",
+                "primary_key": partition_name,
+                "partitions": [partition_name],
+                "matched_keyword": self._matched_keyword(partition_name),
+                "recommended_webex_feature": "Priority Alert",
+                "confidence": "LOW",
+            }
+            options = self._build_options("Priority Alert")
+            summary = (
+                f"Partition '{partition_name}' name suggests selective access "
+                f"(matched keyword '{context['matched_keyword']}'); CUCM "
+                f"caller-specific routing intent inferred from naming only"
+            )
+            decisions.append(
+                self._create_decision(
+                    store=store,
+                    decision_type=DecisionType.FEATURE_APPROXIMATION,
+                    severity="LOW",
+                    summary=summary,
+                    context=context,
+                    options=options,
+                    affected_objects=[pt_id],
+                )
+            )
+        return decisions
+
+    @staticmethod
+    def _matches_vip_keyword(name: str) -> bool:
+        if not name:
+            return False
+        lowered = name.lower()
+        return any(kw in lowered for kw in _VIP_KEYWORDS)
+
+    @staticmethod
+    def _matched_keyword(name: str) -> str:
+        lowered = (name or "").lower()
+        for kw in _VIP_KEYWORDS:
+            if kw in lowered:
+                return kw
+        return ""