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

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

@@ -0,0 +1,143 @@
+# ABOUTME: Auto-discovers and validates all GraphQL blocks from SKILL.md
+# ABOUTME: Runs syntax validation and linter on each extracted query
+
+"""
+Auto-discover & validate all GraphQL code blocks in SKILL.md.
+
+For each ```graphql block found:
+  1. Validate syntax (balanced braces, structure)
+  2. Run the linter and check for ERROR-severity findings
+  3. Extract and report metadata
+
+Incomplete snippets (field-only patterns, filter examples) are
+detected and marked with pytest.xfail.
+
+Run:
+    uv run pytest harness/test_queries.py -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, Severity  # noqa: E402
+from query_validator import (  # noqa: E402
+    validate_query,
+    is_complete_query,
+)
+
+
+def _make_test_id(block: dict) -> str:
+    """Create a readable test ID from a block dict."""
+    section = block.get("section", "unknown") or "unknown"
+    line = block.get("line_number", 0)
+    # Truncate section to 60 chars
+    section = section[:60].replace(" ", "_").replace("/", "_")
+    return f"L{line}_{section}"
+
+
+class TestSkillQueries:
+    """Validate every GraphQL block extracted from SKILL.md."""
+
+    def test_at_least_one_block_found(self, graphql_blocks):
+        """Sanity check: SKILL.md should have GraphQL blocks."""
+        assert len(graphql_blocks) > 0, "No GraphQL blocks found in SKILL.md"
+
+    def test_minimum_block_count(self, graphql_blocks):
+        """SKILL.md should have at least 10 GraphQL blocks."""
+        assert len(graphql_blocks) >= 10, (
+            f"Expected ≥10 GraphQL blocks, found {len(graphql_blocks)}"
+        )
+
+
+def pytest_generate_tests(metafunc):
+    """Parametrize tests with graphql blocks from SKILL.md."""
+    if "query_block" in metafunc.fixturenames:
+        # We need the blocks fixture — get it via the skill_content fixture chain
+        plugin_root = Path(__file__).resolve().parent.parent
+        skill_path = plugin_root / "skills" / "enigma-graphql" / "SKILL.md"
+        if skill_path.exists():
+            sys.path.insert(0, str(plugin_root / "scripts"))
+            from query_validator import extract_graphql_blocks_with_context
+            content = skill_path.read_text(encoding="utf-8")
+            blocks = extract_graphql_blocks_with_context(content)
+            ids = [_make_test_id(b) for b in blocks]
+            metafunc.parametrize("query_block", blocks, ids=ids)
+        else:
+            metafunc.parametrize("query_block", [])
+
+
+class TestQuerySyntax:
+    """Validate syntax of each GraphQL block."""
+
+    def test_syntax_valid(self, query_block):
+        query = query_block["query"]
+        section = query_block.get("section", "")
+        line = query_block.get("line_number", 0)
+
+        # Skip incomplete snippets
+        if not is_complete_query(query):
+            pytest.xfail(
+                f"Incomplete snippet at line {line} "
+                f"(section: {section}) — not a full query"
+            )
+
+        result = validate_query(query)
+        assert result.valid, (
+            f"Syntax error in query at line {line} "
+            f"(section: {section}): {result.errors}"
+        )
+
+
+class TestQueryLint:
+    """Lint each GraphQL block for ERROR-severity findings."""
+
+    def test_no_errors(self, query_block):
+        query = query_block["query"]
+        section = query_block.get("section", "")
+        line = query_block.get("line_number", 0)
+
+        # Skip incomplete snippets
+        if not is_complete_query(query):
+            pytest.xfail(
+                f"Incomplete snippet at line {line} "
+                f"(section: {section}) — not a full query"
+            )
+
+        result = lint_query(query)
+
+        # Filter to only ERROR severity
+        errors = [
+            f for f in result.findings
+            if f.severity == Severity.ERROR
+        ]
+
+        # Build readable message
+        if errors:
+            msg_parts = [
+                f"Query at line {line} (section: {section}) "
+                f"has {len(errors)} error(s):"
+            ]
+            for f in errors:
+                msg_parts.append(f"  [{f.rule_id}] {f.message}")
+            assert False, "\n".join(msg_parts)
+
+
+class TestQueryMetadata:
+    """Verify metadata extraction for complete queries."""
+
+    def test_has_operation_type(self, query_block):
+        query = query_block["query"]
+        line = query_block.get("line_number", 0)
+
+        if not is_complete_query(query):
+            pytest.xfail(f"Incomplete snippet at line {line}")
+
+        result = validate_query(query)
+        assert result.metadata.get("operation_type") is not None, (
+            f"Query at line {line} missing operation_type"
+        )

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

@@ -0,0 +1,351 @@
+# ABOUTME: Static structural checks on the SKILL.md documentation
+# ABOUTME: Validates limits, warnings, and field naming conventions
+
+"""
+Static structural checks on SKILL.md.
+
+These don't test individual queries — they test that the documentation
+itself contains the right guidance, limits, warnings, and conventions.
+
+Run:
+    uv run pytest harness/test_skill_rules.py -v
+"""
+
+import json
+import re
+import sys
+from pathlib import Path
+
+import pytest
+
+# Add scripts/ to sys.path
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "scripts"))
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _extract_json_blocks(content: str) -> list[tuple[str, int]]:
+    """Extract all ```json fenced blocks with line numbers."""
+    results = []
+    for m in re.finditer(r'^```json\s*\n(.*?)\n```', content, re.MULTILINE | re.DOTALL):
+        line_no = content[:m.start()].count('\n') + 1
+        results.append((m.group(1), line_no))
+    return results
+
+
+def _extract_graphql_blocks(content: str) -> list[tuple[str, int]]:
+    """Extract all ```graphql fenced blocks with line numbers."""
+    results = []
+    for m in re.finditer(r'^```graphql\s*\n(.*?)\n```', content, re.MULTILINE | re.DOTALL):
+        line_no = content[:m.start()].count('\n') + 1
+        results.append((m.group(1), line_no))
+    return results
+
+
+def _get_section(content: str, heading_pattern: str) -> str | None:
+    """Extract the content of a section matching the heading pattern."""
+    lines = content.split('\n')
+    capturing = False
+    captured = []
+    heading_level = None
+
+    for line in lines:
+        heading_match = re.match(r'^(#{1,4})\s+(.*)', line)
+        if heading_match:
+            level = len(heading_match.group(1))
+            text = heading_match.group(2).strip()
+            if re.search(heading_pattern, text, re.IGNORECASE):
+                capturing = True
+                heading_level = level
+                captured.append(line)
+                continue
+            elif capturing and level <= heading_level:
+                break
+        if capturing:
+            captured.append(line)
+
+    return '\n'.join(captured) if captured else None
+
+
+def _get_discovery_section(content: str) -> str | None:
+    """Get the Discovery recipe section."""
+    return _get_section(content, r'Discovery.*Find All|Discovery.*Businesses')
+
+
+def _get_ol_section(content: str) -> str | None:
+    """Get the Operating Location Revenue/Card section."""
+    return _get_section(content, r'Operating Location.*Revenue|Operating Location Card')
+
+
+def _get_brand_revenue_section(content: str) -> str | None:
+    """Get the Brand Revenue section."""
+    return _get_section(content, r'Brand Revenue Query')
+
+
+def _get_aggregate_section(content: str) -> str | None:
+    """Get the Aggregate Query section, excluding Count on Search subsection."""
+    full_section = _get_section(content, r'Aggregate Query')
+    if full_section is None:
+        return None
+    # Stop at "Count on Search" subsection to avoid mixing up plural/singular rules
+    lines = full_section.split('\n')
+    result = []
+    for line in lines:
+        if re.match(r'^#{1,4}\s+Count on Search', line, re.IGNORECASE):
+            break
+        result.append(line)
+    return '\n'.join(result) if result else full_section
+
+
+def _get_count_search_section(content: str) -> str | None:
+    """Get the Count on Search section."""
+    return _get_section(content, r'Count on Search')
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+class TestNoLimit50InCodeBlocks:
+    """No `"limit": 50` should appear in any JSON code block."""
+
+    def test_no_limit_50(self, skill_content):
+        json_blocks = _extract_json_blocks(skill_content)
+        violations = []
+        for block_text, line_no in json_blocks:
+            # Look for "limit": 50 or "limit" : 50 patterns
+            if re.search(r'"limit"\s*:\s*50\b', block_text):
+                violations.append(f"Line {line_no}: found '\"limit\": 50' in JSON block")
+        assert not violations, (
+            f"Found limit: 50 in JSON code blocks:\n" +
+            "\n".join(violations)
+        )
+
+
+class TestDiscoveryLimitsLTE10:
+    """Discovery section JSON blocks should have limit ≤ 10."""
+
+    def test_discovery_limits(self, skill_content):
+        section = _get_discovery_section(skill_content)
+        if section is None:
+            pytest.skip("Discovery section not found")
+
+        json_blocks = _extract_json_blocks(section)
+        violations = []
+        for block_text, line_no in json_blocks:
+            for m in re.finditer(r'"limit"\s*:\s*(\d+)', block_text):
+                limit_val = int(m.group(1))
+                if limit_val > 10:
+                    violations.append(
+                        f"Line {line_no}: limit={limit_val} > 10 in Discovery section"
+                    )
+        assert not violations, (
+            f"Discovery section has limit > 10:\n" +
+            "\n".join(violations)
+        )
+
+
+class TestOLFirstLTE5InDiscovery:
+    """Discovery GraphQL should have operatingLocations(first: ≤5)."""
+
+    def test_ol_first_lte_5(self, skill_content):
+        section = _get_discovery_section(skill_content)
+        if section is None:
+            pytest.skip("Discovery section not found")
+
+        graphql_blocks = _extract_graphql_blocks(section)
+        violations = []
+        for block_text, line_no in graphql_blocks:
+            for m in re.finditer(r'operatingLocations\s*\(\s*first\s*:\s*(\d+)', block_text):
+                first_val = int(m.group(1))
+                if first_val > 5:
+                    violations.append(
+                        f"Line {line_no}: operatingLocations(first: {first_val}) > 5 "
+                        f"in Discovery section"
+                    )
+        assert not violations, (
+            f"Discovery section has operatingLocations first > 5:\n" +
+            "\n".join(violations)
+        )
+
+
+class TestNoPlatformBrandIdInOLRecipes:
+    """OL section code blocks should NOT include platformBrandId."""
+
+    def test_no_platform_brand_id(self, skill_content):
+        section = _get_ol_section(skill_content)
+        if section is None:
+            pytest.skip("OL Revenue section not found")
+
+        graphql_blocks = _extract_graphql_blocks(section)
+        json_blocks = _extract_json_blocks(section)
+        violations = []
+
+        for block_text, line_no in graphql_blocks + json_blocks:
+            if "platformBrandId" in block_text:
+                violations.append(
+                    f"Line {line_no}: 'platformBrandId' found in OL section code block"
+                )
+
+        assert not violations, (
+            f"OL section should not reference platformBrandId:\n" +
+            "\n".join(violations)
+        )
+
+
+class TestPlatformBrandIdInBrandRecipes:
+    """Brand revenue code blocks should include platformBrandId."""
+
+    def test_has_platform_brand_id(self, skill_content):
+        section = _get_brand_revenue_section(skill_content)
+        if section is None:
+            pytest.skip("Brand Revenue section not found")
+
+        json_blocks = _extract_json_blocks(section)
+        if not json_blocks:
+            pytest.skip("No JSON blocks in Brand Revenue section")
+
+        found = False
+        for block_text, line_no in json_blocks:
+            if "platformBrandId" in block_text:
+                found = True
+                break
+
+        assert found, (
+            "Brand Revenue section JSON blocks should include platformBrandId filter"
+        )
+
+
+class TestCountSingularInAggregate:
+    """Aggregate count uses singular field names."""
+
+    def test_singular_fields(self, skill_content):
+        section = _get_aggregate_section(skill_content)
+        if section is None:
+            pytest.skip("Aggregate Query section not found")
+
+        graphql_blocks = _extract_graphql_blocks(section)
+        violations = []
+        for block_text, line_no in graphql_blocks:
+            # Look for count(field: "...") — field value should be singular
+            for m in re.finditer(r'count\s*\(\s*field\s*:\s*"(\w+)"', block_text):
+                field_name = m.group(1)
+                # Singular forms: brand, operatingLocation, legalEntity
+                if field_name in ("operatingLocations", "legalEntities", "brands"):
+                    violations.append(
+                        f"Line {line_no}: count(field: \"{field_name}\") should use "
+                        f"singular form in aggregate query"
+                    )
+
+        assert not violations, (
+            f"Aggregate section uses plural field names in count():\n" +
+            "\n".join(violations)
+        )
+
+
+class TestCountPluralInSearch:
+    """Search-level count uses plural field names."""
+
+    def test_plural_fields(self, skill_content):
+        section = _get_count_search_section(skill_content)
+        if section is None:
+            pytest.skip("Count on Search section not found")
+
+        graphql_blocks = _extract_graphql_blocks(section)
+        violations = []
+        for block_text, line_no in graphql_blocks:
+            for m in re.finditer(r'count\s*\(\s*field\s*:\s*"(\w+)"', block_text):
+                field_name = m.group(1)
+                # Plural forms: operatingLocations, legalEntities
+                if field_name in ("operatingLocation", "legalEntity", "brand"):
+                    violations.append(
+                        f"Line {line_no}: count(field: \"{field_name}\") should use "
+                        f"plural form in search-level count"
+                    )
+
+        assert not violations, (
+            f"Search count section uses singular field names in count():\n" +
+            "\n".join(violations)
+        )
+
+
+class TestCoalescePairedWithSkip:
+    """Every @coalesce block should have a corresponding @skip(if: true)."""
+
+    def test_coalesce_has_skip(self, skill_content):
+        graphql_blocks = _extract_graphql_blocks(skill_content)
+        violations = []
+        for block_text, line_no in graphql_blocks:
+            if "@coalesce" in block_text:
+                if "@skip(if: true)" not in block_text and '@skip(if:true)' not in block_text:
+                    violations.append(
+                        f"Line {line_no}: @coalesce found without @skip(if: true)"
+                    )
+
+        assert not violations, (
+            f"@coalesce without @skip(if: true):\n" +
+            "\n".join(violations)
+        )
+
+
+class TestStreet1AgentWarningPresent:
+    """AGENT BEHAVIOR directive about street1 should exist."""
+
+    def test_agent_behavior_present(self, skill_content):
+        assert "AGENT BEHAVIOR" in skill_content, (
+            "SKILL.md should contain an 'AGENT BEHAVIOR' directive for street1"
+        )
+        # Check it mentions street1
+        # Find the AGENT BEHAVIOR block
+        agent_idx = skill_content.index("AGENT BEHAVIOR")
+        context = skill_content[agent_idx:agent_idx + 500]
+        assert "street1" in context.lower() or "street" in context.lower(), (
+            "AGENT BEHAVIOR directive should mention street1/street address"
+        )
+
+
+class TestFranchiseWarningPresent:
+    """Franchise/chain resolution warning section should exist."""
+
+    def test_franchise_section_exists(self, skill_content):
+        assert "Franchise" in skill_content or "franchise" in skill_content, (
+            "SKILL.md should contain franchise/chain resolution guidance"
+        )
+
+    def test_franchise_chain_warning(self, skill_content):
+        # Should have the warning section header
+        assert re.search(
+            r'Franchise.*Chain.*Resolution|Chain.*Resolution',
+            skill_content,
+            re.IGNORECASE,
+        ), "SKILL.md should have a Franchise & Chain Resolution section"
+
+    def test_brand_revenue_chain_warning(self, skill_content):
+        """Brand Revenue section should warn about chain resolution."""
+        section = _get_brand_revenue_section(skill_content)
+        if section is None:
+            pytest.skip("Brand Revenue section not found")
+        assert "chain" in section.lower() or "franchise" in section.lower(), (
+            "Brand Revenue section should warn about franchise/chain resolution"
+        )
+
+
+class TestNoTotalCountInCodeBlocks:
+    """totalCount should never appear in code blocks."""
+
+    def test_no_total_count(self, skill_content):
+        graphql_blocks = _extract_graphql_blocks(skill_content)
+        violations = []
+        for block_text, line_no in graphql_blocks:
+            if "totalCount" in block_text:
+                violations.append(
+                    f"Line {line_no}: 'totalCount' found in GraphQL block "
+                    f"(not supported by Enigma API)"
+                )
+
+        assert not violations, (
+            f"totalCount in code blocks (causes HTTP 400):\n" +
+            "\n".join(violations)
+        )

enigma_api_client/plugins/enigma-api/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "enigma-api-harness"
+version = "0.1.0"
+description = "Query linter and test harness for the enigma-graphql skill"
+requires-python = ">=3.11"
+dependencies = ["pytest>=8.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["harness"]