enigma-api-client 0.3.1__py3-none-any.whl

enigma_api_client/plugins/enigma-api/harness/test_linter.py

@@ -0,0 +1,863 @@
+# ABOUTME: Unit tests for the 18 lint rules in lint_query.py
+# ABOUTME: Each rule has a test class with bad (triggers) and good (clean) queries
+
+"""
+Unit tests for the Enigma GraphQL query linter.
+
+Each ENIGMA-NNN rule gets its own test class with:
+  - test_bad_query_triggers — a query that SHOULD fire the rule
+  - test_good_query_clean   — a query that should NOT fire the rule
+
+Run:
+    uv run pytest harness/test_linter.py -v
+    uv run pytest harness/test_linter.py -k "ENIGMA_006" -v
+"""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+# Add scripts/ to sys.path
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "scripts"))
+
+from lint_query import lint_query, LintResult, Severity  # noqa: E402
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def assert_triggers(query: str, rule_id: str, *, severity: Severity | None = None):
+    """Assert that linting the query triggers the given rule."""
+    result = lint_query(query)
+    rule_ids = [f.rule_id for f in result.findings]
+    assert rule_id in rule_ids, (
+        f"Expected rule {rule_id} to fire but got: {rule_ids}"
+    )
+    if severity is not None:
+        for f in result.findings:
+            if f.rule_id == rule_id:
+                assert f.severity == severity, (
+                    f"Expected {severity.value} but got {f.severity.value}"
+                )
+
+
+def assert_clean(query: str, rule_id: str):
+    """Assert that linting the query does NOT trigger the given rule."""
+    result = lint_query(query)
+    rule_ids = [f.rule_id for f in result.findings]
+    assert rule_id not in rule_ids, (
+        f"Rule {rule_id} should NOT fire but it did: "
+        + "; ".join(f.message for f in result.findings if f.rule_id == rule_id)
+    )
+
+
+# ---------------------------------------------------------------------------
+# ENIGMA-001: LegalEntity.persons usage
+# ---------------------------------------------------------------------------
+
+class TestENIGMA001PersonsOnLE:
+    RULE = "ENIGMA-001"
+
+    def test_bad_query_triggers(self):
+        query = """
+        query Bad($searchInput: SearchInput!) {
+          search(searchInput: $searchInput) {
+            ... on LegalEntity {
+              id
+              persons(first: 10) {
+                edges { node { names { edges { node { fullName } } } } }
+              }
+            }
+          }
+        }
+        """
+        assert_triggers(query, self.RULE, severity=Severity.ERROR)
+
+    def test_good_query_uses_registered_entities(self):
+        query = """
+        query Good($searchInput: SearchInput!) {
+          search(searchInput: $searchInput) {
+            ... on LegalEntity {
+              id
+              registeredEntities {
+                edges {
+                  node {
+                    registrations(first: 5) {
+                      edges { node { roles(first: 20) { edges { node { jobTitle } } } } }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+
+# ---------------------------------------------------------------------------
+# ENIGMA-002: Direct roles on LegalEntity
+# ---------------------------------------------------------------------------
+
+class TestENIGMA002DirectRolesOnLE:
+    RULE = "ENIGMA-002"
+
+    def test_bad_direct_roles(self):
+        query = """
+        query Bad($searchInput: SearchInput!) {
+          search(searchInput: $searchInput) {
+            ... on LegalEntity {
+              id
+              roles(first: 20) {
+                edges { node { jobTitle } }
+              }
+            }
+          }
+        }
+        """
+        assert_triggers(query, self.RULE, severity=Severity.ERROR)
+
+    def test_good_roles_under_registered_entities(self):
+        query = """
+        query Good($searchInput: SearchInput!) {
+          search(searchInput: $searchInput) {
+            ... on LegalEntity {
+              id
+              registeredEntities {
+                edges {
+                  node {
+                    registrations(first: 5) {
+                      edges {
+                        node {
+                          roles(first: 20) {
+                            edges { node { jobTitle } }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+
+# ---------------------------------------------------------------------------
+# ENIGMA-003: Missing pagination (first: N)
+# ---------------------------------------------------------------------------
+
+class TestENIGMA003MissingPagination:
+    RULE = "ENIGMA-003"
+
+    def test_bad_no_first(self):
+        query = """
+        query Bad($searchInput: SearchInput!) {
+          search(searchInput: $searchInput) {
+            ... on Brand {
+              id
+              operatingLocations {
+                edges { node { id } }
+              }
+            }
+          }
+        }
+        """
+        assert_triggers(query, self.RULE, severity=Severity.ERROR)
+
+    def test_good_with_first(self):
+        query = """
+        query Good($searchInput: SearchInput!) {
+          search(searchInput: $searchInput) {
+            ... on Brand {
+              id
+              operatingLocations(first: 10) {
+                edges { node { id } }
+              }
+            }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+    def test_skip_directive_exempt(self):
+        """Fields with @skip(if: true) are exempt from pagination."""
+        query = """
+        query Skip($searchInput: SearchInput!) {
+          search(searchInput: $searchInput) {
+            ... on OperatingLocation {
+              legalEntities @skip(if: true) {
+                edges { node { tins(first: 1) { edges { node { tin } } } } }
+              }
+            }
+          }
+        }
+        """
+        # Should not trigger for legalEntities since it has @skip
+        result = lint_query(query)
+        le_findings = [f for f in result.findings
+                       if f.rule_id == self.RULE and "legalEntities" in f.message]
+        assert len(le_findings) == 0
+
+
+# ---------------------------------------------------------------------------
+# ENIGMA-004: Missing entityType on searchInput
+# ---------------------------------------------------------------------------
+
+class TestENIGMA004MissingEntityType:
+    RULE = "ENIGMA-004"
+
+    def test_bad_no_entity_type(self):
+        query = """
+        query Bad {
+          search(searchInput: { name: "Acme" }) {
+            ... on Brand { id }
+          }
+        }
+        """
+        assert_triggers(query, self.RULE, severity=Severity.ERROR)
+
+    def test_good_with_entity_type(self):
+        query = """
+        query Good {
+          search(searchInput: { name: "Acme", entityType: BRAND }) {
+            ... on Brand { id }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+    def test_variable_is_exempt(self):
+        """When searchInput is a $variable, we can't lint it inline."""
+        query = """
+        query Good($searchInput: SearchInput!) {
+          search(searchInput: $searchInput) {
+            ... on Brand { id }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+
+# ---------------------------------------------------------------------------
+# ENIGMA-005: prompt with non-BRAND entityType
+# ---------------------------------------------------------------------------
+
+class TestENIGMA005PromptNonBrand:
+    RULE = "ENIGMA-005"
+
+    def test_bad_prompt_with_ol(self):
+        query = """
+        query Bad {
+          search(searchInput: { prompt: "coffee shop", entityType: OPERATING_LOCATION }) {
+            ... on OperatingLocation { id }
+          }
+        }
+        """
+        assert_triggers(query, self.RULE, severity=Severity.ERROR)
+
+    def test_good_prompt_with_brand(self):
+        query = """
+        query Good {
+          search(searchInput: { prompt: "coffee shop", entityType: BRAND }) {
+            ... on Brand { id }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+
+# ---------------------------------------------------------------------------
+# ENIGMA-006: Unfiltered cardTransactions
+# ---------------------------------------------------------------------------
+
+class TestENIGMA006UnfilteredCardTransactions:
+    RULE = "ENIGMA-006"
+
+    def test_bad_no_conditions(self):
+        query = """
+        query Bad {
+          search(searchInput: { name: "Acme", entityType: BRAND }) {
+            ... on Brand {
+              cardTransactions(first: 50) {
+                edges { node { projectedQuantity } }
+              }
+            }
+          }
+        }
+        """
+        assert_triggers(query, self.RULE, severity=Severity.ERROR)
+
+    def test_good_with_conditions(self):
+        query = """
+        query Good {
+          search(searchInput: { name: "Acme", entityType: BRAND }) {
+            ... on Brand {
+              cardTransactions(first: 1, conditions: $revCond) {
+                edges { node { projectedQuantity } }
+              }
+            }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+
+# ---------------------------------------------------------------------------
+# ENIGMA-007: Deep traversal (>5 levels)
+# ---------------------------------------------------------------------------
+
+class TestENIGMA007DeepTraversal:
+    RULE = "ENIGMA-007"
+
+    def test_bad_6_levels(self):
+        """6 levels of non-leaf connections should trigger."""
+        query = """
+        query Deep($searchInput: SearchInput!) {
+          search(searchInput: $searchInput) {
+            ... on Brand {
+              operatingLocations(first: 5) {
+                edges {
+                  node {
+                    brands(first: 3) {
+                      edges {
+                        node {
+                          operatingLocations(first: 3) {
+                            edges {
+                              node {
+                                brands(first: 3) {
+                                  edges {
+                                    node {
+                                      operatingLocations(first: 3) {
+                                        edges {
+                                          node {
+                                            brands(first: 3) {
+                                              edges { node { id } }
+                                            }
+                                          }
+                                        }
+                                      }
+                                    }
+                                  }
+                                }
+                              }
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+        """
+        assert_triggers(query, self.RULE, severity=Severity.ERROR)
+
+    def test_good_3_levels(self):
+        query = """
+        query Shallow($searchInput: SearchInput!) {
+          search(searchInput: $searchInput) {
+            ... on Brand {
+              operatingLocations(first: 5) {
+                edges {
+                  node {
+                    brands(first: 1) {
+                      edges { node { id } }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+
+# ---------------------------------------------------------------------------
+# ENIGMA-008: roles on Brand
+# ---------------------------------------------------------------------------
+
+class TestENIGMA008RolesOnBrand:
+    RULE = "ENIGMA-008"
+
+    def test_bad_roles_on_brand(self):
+        query = """
+        query Bad($searchInput: SearchInput!) {
+          search(searchInput: $searchInput) {
+            ... on Brand {
+              id
+              roles(first: 10) {
+                edges { node { jobTitle } }
+              }
+            }
+          }
+        }
+        """
+        assert_triggers(query, self.RULE, severity=Severity.ERROR)
+
+    def test_good_roles_on_registration(self):
+        """roles under legalEntities > registeredEntities > registrations is fine."""
+        query = """
+        query Good($searchInput: SearchInput!) {
+          search(searchInput: $searchInput) {
+            ... on Brand {
+              id
+              legalEntities(first: 5) {
+                edges {
+                  node {
+                    registeredEntities(first: 3) {
+                      edges {
+                        node {
+                          registrations(first: 5) {
+                            edges {
+                              node {
+                                roles(first: 20) {
+                                  edges { node { jobTitle } }
+                                }
+                              }
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+
+# ---------------------------------------------------------------------------
+# ENIGMA-009: Multi-field filter without AND/OR
+# ---------------------------------------------------------------------------
+
+class TestENIGMA009MultiFieldFilter:
+    RULE = "ENIGMA-009"
+
+    def test_bad_multiple_keys_no_wrapper(self):
+        query = """
+        query Bad {
+          search(searchInput: { name: "Acme", entityType: BRAND }) {
+            ... on Brand {
+              operatingLocations(first: 10, conditions: {
+                filter: { EQ: ["addresses.state", "NY"], NE: ["addresses.city", "BUFFALO"] }
+              }) {
+                edges { node { id } }
+              }
+            }
+          }
+        }
+        """
+        assert_triggers(query, self.RULE, severity=Severity.ERROR)
+
+    def test_good_with_and_wrapper(self):
+        query = """
+        query Good {
+          search(searchInput: { name: "Acme", entityType: BRAND }) {
+            ... on Brand {
+              operatingLocations(first: 10, conditions: {
+                filter: { AND: [{ EQ: ["addresses.state", "NY"] }, { NE: ["addresses.city", "BUFFALO"] }] }
+              }) {
+                edges { node { id } }
+              }
+            }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+
+# ---------------------------------------------------------------------------
+# ENIGMA-010: Missing search limit
+# ---------------------------------------------------------------------------
+
+class TestENIGMA010MissingSearchLimit:
+    RULE = "ENIGMA-010"
+
+    def test_bad_no_limit(self):
+        query = """
+        query Bad {
+          search(searchInput: { name: "Acme", entityType: BRAND }) {
+            ... on Brand { id }
+          }
+        }
+        """
+        assert_triggers(query, self.RULE, severity=Severity.ERROR)
+
+    def test_good_with_limit(self):
+        query = """
+        query Good {
+          search(searchInput: { name: "Acme", entityType: BRAND, conditions: { limit: 10 } }) {
+            ... on Brand { id }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+    def test_variable_exempt(self):
+        query = """
+        query Good($searchInput: SearchInput!) {
+          search(searchInput: $searchInput) {
+            ... on Brand { id }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+
+# ---------------------------------------------------------------------------
+# ENIGMA-011: HAS operator usage
+# ---------------------------------------------------------------------------
+
+class TestENIGMA011HasOperator:
+    RULE = "ENIGMA-011"
+
+    def test_bad_has_operator(self):
+        query = """
+        query Bad {
+          search(searchInput: { name: "Acme", entityType: BRAND, conditions: { limit: 10 } }) {
+            ... on Brand {
+              operatingLocations(first: 10, conditions: {
+                filter: { HAS: ["phoneNumbers.phoneNumber"] }
+              }) {
+                edges { node { id } }
+              }
+            }
+          }
+        }
+        """
+        assert_triggers(query, self.RULE, severity=Severity.WARNING)
+
+    def test_good_no_has(self):
+        query = """
+        query Good {
+          search(searchInput: { name: "Acme", entityType: BRAND, conditions: { limit: 10 } }) {
+            ... on Brand {
+              operatingLocations(first: 10, conditions: {
+                filter: { IS_NOT_NULL: ["phoneNumbers.phoneNumber"] }
+              }) {
+                edges { node { id } }
+              }
+            }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+
+# ---------------------------------------------------------------------------
+# ENIGMA-012: Conditions on unsupported fields
+# ---------------------------------------------------------------------------
+
+class TestENIGMA012ConditionsUnsupported:
+    RULE = "ENIGMA-012"
+
+    def test_bad_conditions_on_roles(self):
+        query = """
+        query Bad($searchInput: SearchInput!) {
+          search(searchInput: $searchInput) {
+            ... on LegalEntity {
+              registeredEntities {
+                edges {
+                  node {
+                    registrations(first: 5) {
+                      edges {
+                        node {
+                          roles(first: 20, conditions: { filter: { EQ: ["jobTitle", "CEO"] } }) {
+                            edges { node { jobTitle } }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+        """
+        assert_triggers(query, self.RULE, severity=Severity.WARNING)
+
+    def test_good_no_conditions_on_roles(self):
+        query = """
+        query Good($searchInput: SearchInput!) {
+          search(searchInput: $searchInput) {
+            ... on LegalEntity {
+              registeredEntities {
+                edges {
+                  node {
+                    registrations(first: 5) {
+                      edges {
+                        node {
+                          roles(first: 20) {
+                            edges { node { jobTitle } }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+
+# ---------------------------------------------------------------------------
+# ENIGMA-013: Address-only search
+# ---------------------------------------------------------------------------
+
+class TestENIGMA013AddressOnlySearch:
+    RULE = "ENIGMA-013"
+
+    def test_bad_address_only(self):
+        query = """
+        query Bad {
+          search(searchInput: { entityType: OPERATING_LOCATION, address: { city: "NEW YORK", state: "NY" }, conditions: { limit: 10 } }) {
+            ... on OperatingLocation { id }
+          }
+        }
+        """
+        assert_triggers(query, self.RULE, severity=Severity.WARNING)
+
+    def test_good_name_plus_address(self):
+        query = """
+        query Good {
+          search(searchInput: { name: "Roto-Rooter", entityType: OPERATING_LOCATION, address: { street1: "123 Main", city: "Tulsa", state: "OK" }, conditions: { limit: 10 } }) {
+            ... on OperatingLocation { id }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+
+# ---------------------------------------------------------------------------
+# ENIGMA-014: rawQuantity usage
+# ---------------------------------------------------------------------------
+
+class TestENIGMA014RawQuantity:
+    RULE = "ENIGMA-014"
+
+    def test_bad_raw_quantity(self):
+        query = """
+        query Bad {
+          search(searchInput: { name: "Acme", entityType: BRAND, conditions: { limit: 1 } }) {
+            ... on Brand {
+              cardTransactions(first: 1, conditions: $cond) {
+                edges { node { rawQuantity } }
+              }
+            }
+          }
+        }
+        """
+        assert_triggers(query, self.RULE, severity=Severity.WARNING)
+
+    def test_good_projected_quantity(self):
+        query = """
+        query Good {
+          search(searchInput: { name: "Acme", entityType: BRAND, conditions: { limit: 1 } }) {
+            ... on Brand {
+              cardTransactions(first: 1, conditions: $cond) {
+                edges { node { projectedQuantity } }
+              }
+            }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+
+# ---------------------------------------------------------------------------
+# ENIGMA-015: postalCode in return fields
+# ---------------------------------------------------------------------------
+
+class TestENIGMA015PostalCodeInReturn:
+    RULE = "ENIGMA-015"
+
+    def test_bad_postal_code_in_node(self):
+        query = """
+        query Bad {
+          search(searchInput: { name: "Acme", entityType: BRAND, conditions: { limit: 1 } }) {
+            ... on Brand {
+              operatingLocations(first: 5) {
+                edges {
+                  node {
+                    addresses(first: 1) {
+                      edges { node { fullAddress postalCode } }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+        """
+        assert_triggers(query, self.RULE, severity=Severity.WARNING)
+
+    def test_good_zip_in_node(self):
+        query = """
+        query Good {
+          search(searchInput: { name: "Acme", entityType: BRAND, conditions: { limit: 1 } }) {
+            ... on Brand {
+              operatingLocations(first: 5) {
+                edges {
+                  node {
+                    addresses(first: 1) {
+                      edges { node { fullAddress zip } }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+    def test_postal_code_in_search_input_is_ok(self):
+        """postalCode is correct in AddressInput (searchInput)."""
+        query = """
+        query OK {
+          search(searchInput: { name: "Acme", entityType: OPERATING_LOCATION, address: { postalCode: "10001" }, conditions: { limit: 10 } }) {
+            ... on OperatingLocation {
+              addresses(first: 1) {
+                edges { node { fullAddress zip } }
+              }
+            }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+
+# ---------------------------------------------------------------------------
+# ENIGMA-016: Address ranking on person search
+# ---------------------------------------------------------------------------
+
+class TestENIGMA016AddressRanking:
+    RULE = "ENIGMA-016"
+
+    def test_info_address_on_person(self):
+        query = """
+        query Person {
+          search(searchInput: { entityType: PERSON, person: { firstName: "John", lastName: "Doe" }, address: { state: "NY" }, conditions: { limit: 10 } }) {
+            ... on Person { id }
+          }
+        }
+        """
+        assert_triggers(query, self.RULE, severity=Severity.INFO)
+
+    def test_clean_address_on_brand(self):
+        query = """
+        query Brand {
+          search(searchInput: { name: "Acme", entityType: BRAND, address: { state: "NY" }, conditions: { limit: 10 } }) {
+            ... on Brand { id }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+
+# ---------------------------------------------------------------------------
+# ENIGMA-017: LegalEntity → Brand traversal trust
+# ---------------------------------------------------------------------------
+
+class TestENIGMA017LEBrandTrust:
+    RULE = "ENIGMA-017"
+
+    def test_info_le_to_brands(self):
+        query = """
+        query LEBrands($searchInput: SearchInput!) {
+          search(searchInput: $searchInput) {
+            ... on LegalEntity {
+              id
+              brands(first: 5) {
+                edges { node { id } }
+              }
+            }
+          }
+        }
+        """
+        assert_triggers(query, self.RULE, severity=Severity.INFO)
+
+    def test_clean_no_brands_on_le(self):
+        query = """
+        query LEOnly($searchInput: SearchInput!) {
+          search(searchInput: $searchInput) {
+            ... on LegalEntity {
+              id
+              names { edges { node { name } } }
+            }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+
+# ---------------------------------------------------------------------------
+# ENIGMA-018: Missing operation name
+# ---------------------------------------------------------------------------
+
+class TestENIGMA018MissingOperationName:
+    RULE = "ENIGMA-018"
+
+    def test_bad_anonymous_query(self):
+        query = """
+        {
+          search(searchInput: { name: "Acme", entityType: BRAND, conditions: { limit: 1 } }) {
+            ... on Brand { id }
+          }
+        }
+        """
+        assert_triggers(query, self.RULE, severity=Severity.INFO)
+
+    def test_bad_query_without_name(self):
+        query = """
+        query($searchInput: SearchInput!) {
+          search(searchInput: $searchInput) {
+            ... on Brand { id }
+          }
+        }
+        """
+        assert_triggers(query, self.RULE, severity=Severity.INFO)
+
+    def test_good_named_query(self):
+        query = """
+        query BrandSearch($searchInput: SearchInput!) {
+          search(searchInput: $searchInput) {
+            ... on Brand { id }
+          }
+        }
+        """
+        assert_clean(query, self.RULE)
+
+
+# ---------------------------------------------------------------------------
+# Parse errors
+# ---------------------------------------------------------------------------
+
+class TestParseErrors:
+    def test_empty_query(self):
+        result = lint_query("")
+        assert not result.query_valid
+        assert any(f.rule_id == "PARSE" for f in result.findings)
+
+    def test_unbalanced_braces(self):
+        result = lint_query("query Bad { search(")
+        assert not result.query_valid
+
+    def test_no_braces(self):
+        result = lint_query("just some text")
+        assert not result.query_valid