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

enigma_api_client/plugins/enigma-api/scripts/generate_report.py

@@ -0,0 +1,384 @@
+# ABOUTME: Generates a concise MR-ready validation report for SKILL.md
+# ABOUTME: Runs linter, query checks, and structural rules; outputs markdown summary
+
+"""
+Enigma GraphQL Skill — Validation Report Generator
+
+Runs all checks against SKILL.md and prints a concise markdown report
+suitable for pasting into an MR description or CI output.
+
+Usage:
+    python scripts/generate_report.py                  # default: skills/enigma-graphql/SKILL.md
+    python scripts/generate_report.py path/to/SKILL.md # custom path
+
+Exit code: 0 if all critical checks pass, 1 otherwise.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+# Add scripts/ to path
+SCRIPTS_DIR = Path(__file__).resolve().parent
+PLUGIN_ROOT = SCRIPTS_DIR.parent
+sys.path.insert(0, str(SCRIPTS_DIR))
+
+from lint_query import lint_query, Severity  # noqa: E402
+from query_validator import (  # noqa: E402
+    validate_query,
+    extract_graphql_blocks_with_context,
+    is_complete_query,
+)
+
+
+# ---------------------------------------------------------------------------
+# Check definitions
+# ---------------------------------------------------------------------------
+
+STRUCTURAL_CHECKS: list[dict] = [
+    {
+        "id": "S-01",
+        "name": "No limit:50 in JSON blocks",
+        "check": lambda c: not bool(re.search(r'"limit"\s*:\s*50\b', _json_blocks(c))),
+    },
+    {
+        "id": "S-02",
+        "name": "Discovery limits ≤ 10",
+        "check": lambda c: _check_discovery_limits(c),
+    },
+    {
+        "id": "S-03",
+        "name": "Discovery OL first ≤ 5",
+        "check": lambda c: _check_discovery_ol_first(c),
+    },
+    {
+        "id": "S-04",
+        "name": "No platformBrandId in OL recipes",
+        "check": lambda c: "platformBrandId" not in _get_section_blocks(c, r"Operating Location.*Revenue", "all"),
+    },
+    {
+        "id": "S-05",
+        "name": "platformBrandId in Brand revenue",
+        "check": lambda c: "platformBrandId" in _get_section_blocks(c, r"Brand Revenue Query", "json"),
+    },
+    {
+        "id": "S-06",
+        "name": "Singular count fields in aggregate",
+        "check": lambda c: _check_aggregate_singular(c),
+    },
+    {
+        "id": "S-07",
+        "name": "Plural count fields in search",
+        "check": lambda c: _check_search_plural(c),
+    },
+    {
+        "id": "S-08",
+        "name": "@coalesce paired with @skip",
+        "check": lambda c: _check_coalesce_skip(c),
+    },
+    {
+        "id": "S-09",
+        "name": "street1 AGENT BEHAVIOR warning",
+        "check": lambda c: "AGENT BEHAVIOR" in c and "street" in c[c.index("AGENT BEHAVIOR"):c.index("AGENT BEHAVIOR") + 500].lower(),
+    },
+    {
+        "id": "S-10",
+        "name": "Franchise/chain warning present",
+        "check": lambda c: bool(re.search(r"Franchise.*Chain.*Resolution|Chain.*Resolution", c, re.IGNORECASE)),
+    },
+    {
+        "id": "S-11",
+        "name": "No totalCount in code blocks",
+        "check": lambda c: "totalCount" not in _graphql_blocks_text(c),
+    },
+]
+
+
+# ---------------------------------------------------------------------------
+# Helpers for structural checks
+# ---------------------------------------------------------------------------
+
+def _json_blocks(content: str) -> str:
+    """Concatenate all ```json blocks."""
+    return "\n".join(m.group(1) for m in re.finditer(r"^```json\s*\n(.*?)\n```", content, re.M | re.S))
+
+
+def _graphql_blocks_text(content: str) -> str:
+    """Concatenate all ```graphql blocks."""
+    return "\n".join(m.group(1) for m in re.finditer(r"^```graphql\s*\n(.*?)\n```", content, re.M | re.S))
+
+
+def _get_section(content: str, heading_pattern: str) -> str | None:
+    lines = content.split("\n")
+    capturing = False
+    captured: list[str] = []
+    heading_level = None
+    for line in lines:
+        hm = re.match(r"^(#{1,4})\s+(.*)", line)
+        if hm:
+            level = len(hm.group(1))
+            text = hm.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_section_blocks(content: str, heading_pattern: str, block_type: str) -> str:
+    sec = _get_section(content, heading_pattern)
+    if not sec:
+        return ""
+    if block_type == "json":
+        return _json_blocks(sec)
+    elif block_type == "graphql":
+        return _graphql_blocks_text(sec)
+    else:
+        return _json_blocks(sec) + "\n" + _graphql_blocks_text(sec)
+
+
+def _check_discovery_limits(content: str) -> bool:
+    sec = _get_section(content, r"Discovery.*Find All|Discovery.*Businesses")
+    if not sec:
+        return True
+    for m in re.finditer(r'"limit"\s*:\s*(\d+)', _json_blocks(sec)):
+        if int(m.group(1)) > 10:
+            return False
+    return True
+
+
+def _check_discovery_ol_first(content: str) -> bool:
+    sec = _get_section(content, r"Discovery.*Find All|Discovery.*Businesses")
+    if not sec:
+        return True
+    for m in re.finditer(r"operatingLocations\s*\(\s*first\s*:\s*(\d+)", _graphql_blocks_text(sec)):
+        if int(m.group(1)) > 5:
+            return False
+    return True
+
+
+def _check_aggregate_singular(content: str) -> bool:
+    sec = _get_section(content, r"Aggregate Query")
+    if not sec:
+        return True
+    # Stop at Count on Search subsection
+    lines = sec.split("\n")
+    trimmed = []
+    for line in lines:
+        if re.match(r"^#{1,4}\s+Count on Search", line, re.IGNORECASE):
+            break
+        trimmed.append(line)
+    gql = _graphql_blocks_text("\n".join(trimmed))
+    for m in re.finditer(r'count\s*\(\s*field\s*:\s*"(\w+)"', gql):
+        if m.group(1) in ("operatingLocations", "legalEntities", "brands"):
+            return False
+    return True
+
+
+def _check_search_plural(content: str) -> bool:
+    sec = _get_section(content, r"Count on Search")
+    if not sec:
+        return True
+    gql = _graphql_blocks_text(sec)
+    for m in re.finditer(r'count\s*\(\s*field\s*:\s*"(\w+)"', gql):
+        if m.group(1) in ("operatingLocation", "legalEntity", "brand"):
+            return False
+    return True
+
+
+def _check_coalesce_skip(content: str) -> bool:
+    for m in re.finditer(r"^```graphql\s*\n(.*?)\n```", content, re.M | re.S):
+        block = m.group(1)
+        if "@coalesce" in block and "@skip(if: true)" not in block and "@skip(if:true)" not in block:
+            return False
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Report generator
+# ---------------------------------------------------------------------------
+
+def generate_report(skill_path: Path) -> tuple[str, bool]:
+    """Generate a markdown validation report. Returns (report_text, all_passed)."""
+    content = skill_path.read_text(encoding="utf-8")
+    blocks = extract_graphql_blocks_with_context(content)
+
+    lines: list[str] = []
+    all_passed = True
+
+    # Header
+    lines.append("## SKILL.md Validation Report")
+    lines.append("")
+    lines.append(f"**File**: `{skill_path.name}` | **Date**: {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M UTC')}")
+    lines.append("")
+
+    # ── Section 1: Structural checks ──────────────────────────────
+    lines.append("### Structural Checks")
+    lines.append("")
+    lines.append("| # | Check | Result |")
+    lines.append("|---|-------|--------|")
+
+    structural_pass = 0
+    structural_fail = 0
+    for check in STRUCTURAL_CHECKS:
+        try:
+            passed = check["check"](content)
+        except Exception:
+            passed = False
+        icon = "✅" if passed else "❌"
+        if not passed:
+            structural_fail += 1
+            all_passed = False
+        else:
+            structural_pass += 1
+        lines.append(f"| {check['id']} | {check['name']} | {icon} |")
+
+    lines.append("")
+    lines.append(f"> {structural_pass} passed, {structural_fail} failed")
+    lines.append("")
+
+    # ── Section 2: Query validation ───────────────────────────────
+    complete = [b for b in blocks if is_complete_query(b["query"])]
+    snippets = [b for b in blocks if not is_complete_query(b["query"])]
+
+    syntax_pass = 0
+    syntax_fail = 0
+    lint_pass = 0
+    lint_fail = 0
+    lint_failures: list[str] = []
+
+    for block in complete:
+        q = block["query"]
+        section = block.get("section", "?")
+        line = block.get("line_number", 0)
+        label = f"L{line} {section}"[:60]
+
+        # Syntax
+        vr = validate_query(q)
+        if vr.valid:
+            syntax_pass += 1
+        else:
+            syntax_fail += 1
+            all_passed = False
+
+        # Lint (errors only)
+        lr = lint_query(q)
+        errors = [f for f in lr.findings if f.severity == Severity.ERROR]
+        if errors:
+            lint_fail += 1
+            all_passed = False
+            rules = ", ".join(sorted({f.rule_id for f in errors}))
+            lint_failures.append(f"  - **{label}**: {rules}")
+        else:
+            lint_pass += 1
+
+    lines.append("### Query Validation")
+    lines.append("")
+    lines.append(f"**{len(complete)}** complete queries found, **{len(snippets)}** snippets (skipped)")
+    lines.append("")
+    lines.append("| Check | Passed | Failed |")
+    lines.append("|-------|--------|--------|")
+    lines.append(f"| Syntax (balanced braces, structure) | {syntax_pass} | {syntax_fail} |")
+    lines.append(f"| Lint (ERROR-severity rules) | {lint_pass} | {lint_fail} |")
+    lines.append("")
+
+    if lint_failures:
+        lines.append("<details><summary>Lint failures</summary>")
+        lines.append("")
+        lines.extend(lint_failures)
+        lines.append("")
+        lines.append("</details>")
+        lines.append("")
+
+    # ── Section 3: Per-rule results ─────────────────────────────
+    rule_descriptions = {
+        "ENIGMA-001": ("ERROR", "LegalEntity.persons usage (usually empty)"),
+        "ENIGMA-002": ("ERROR", "Direct roles on LegalEntity"),
+        "ENIGMA-003": ("ERROR", "Missing pagination (first: N)"),
+        "ENIGMA-004": ("ERROR", "Missing entityType on searchInput"),
+        "ENIGMA-005": ("ERROR", "prompt with non-BRAND entity"),
+        "ENIGMA-006": ("ERROR", "Unfiltered cardTransactions"),
+        "ENIGMA-007": ("ERROR", "Deep traversal (>5 levels)"),
+        "ENIGMA-008": ("ERROR", "roles on Brand (invalid field)"),
+        "ENIGMA-009": ("ERROR", "Multi-field filter without AND/OR"),
+        "ENIGMA-010": ("ERROR", "Missing search limit"),
+        "ENIGMA-011": ("WARNING", "Unreliable HAS operator"),
+        "ENIGMA-012": ("WARNING", "Conditions on unsupported fields"),
+        "ENIGMA-013": ("WARNING", "Address-only search"),
+        "ENIGMA-014": ("WARNING", "rawQuantity instead of projectedQuantity"),
+        "ENIGMA-015": ("WARNING", "postalCode in return fields (use zip)"),
+        "ENIGMA-016": ("INFO", "Address ranking on PERSON search"),
+        "ENIGMA-017": ("INFO", "LegalEntity → Brand ~30% error rate"),
+        "ENIGMA-018": ("INFO", "Missing operation name"),
+    }
+
+    # Count how many queries triggered each rule
+    rule_trigger_count: dict[str, int] = {rid: 0 for rid in rule_descriptions}
+    for block in complete:
+        lr = lint_query(block["query"])
+        for f in lr.findings:
+            if f.rule_id in rule_trigger_count:
+                rule_trigger_count[f.rule_id] += 1
+
+    lines.append("### Lint Rules")
+    lines.append("")
+    lines.append(f"| Rule | Severity | Description | Result |")
+    lines.append("|------|----------|-------------|--------|")
+    for rule_id, (sev, desc) in rule_descriptions.items():
+        count = rule_trigger_count[rule_id]
+        if count == 0:
+            icon = "✅ Pass"
+        elif sev == "INFO":
+            icon = f"ℹ️ {count} note(s)"
+        elif sev == "WARNING":
+            icon = f"⚠️ {count} warning(s)"
+        else:
+            icon = f"❌ {count} error(s)"
+        lines.append(f"| {rule_id} | {sev} | {desc} | {icon} |")
+
+    lines.append("")
+
+    # ── Footer ────────────────────────────────────────────────────
+    total_checks = structural_pass + structural_fail + syntax_pass + syntax_fail + lint_pass + lint_fail
+    total_passed = structural_pass + syntax_pass + lint_pass
+    total_failed = structural_fail + syntax_fail + lint_fail
+
+    if all_passed:
+        lines.append(f"**Result: ✅ ALL CHECKS PASSED** ({total_passed}/{total_checks})")
+    else:
+        lines.append(f"**Result: ❌ {total_failed} CHECK(S) FAILED** ({total_passed}/{total_checks} passed)")
+
+    lines.append("")
+
+    return "\n".join(lines), all_passed
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main():
+    if len(sys.argv) > 1:
+        skill_path = Path(sys.argv[1])
+    else:
+        skill_path = PLUGIN_ROOT / "skills" / "enigma-graphql" / "SKILL.md"
+
+    if not skill_path.exists():
+        print(f"ERROR: {skill_path} not found", file=sys.stderr)
+        sys.exit(1)
+
+    report, passed = generate_report(skill_path)
+    print(report)
+    sys.exit(0 if passed else 1)
+
+
+if __name__ == "__main__":
+    main()