GQLLint -- GraphQL Anti-Pattern & Security Analyzer

GQLLint scans codebases for GraphQL anti-patterns: query depth/complexity issues, resolver N+1 problems, over/under fetching, rate limiting & auth gaps, schema design issues, and client query safety problems. It uses regex-based pattern matching against 90 GraphQL-specific patterns across 6 categories, lefthook for git hook integration, and produces markdown reports with actionable remediation guidance. 100% local. Zero telemetry.

Note: GQLLint focuses on GraphQL-specific patterns (schema definitions, resolvers, client queries, server configuration). It does NOT analyze general JavaScript/TypeScript quality or REST API patterns.

Commands

Free Tier (No license required)

gqllint scan [file|directory]

One-shot GraphQL quality scan of files or directories.

How to execute:

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [target]

What it does:

1. Accepts a file path or directory (defaults to current directory)
2. Discovers all source files (skips .git, node_modules, binaries, images, .min.js)
3. Runs 30 GraphQL patterns against each file (free tier limit)
4. Calculates a GraphQL quality score (0-100) per file and overall
5. Grades: A (90-100), B (80-89), C (70-79), D (60-69), F (<60)
6. Outputs findings with: file, line number, check ID, severity, description, recommendation
7. Exit code 0 if score >= 70, exit code 1 if GraphQL quality is poor
8. Free tier limited to first 30 patterns (QD + RN categories)

Example usage scenarios:

• "Scan my code for GraphQL issues" -> runs gqllint scan .
• "Check this file for N+1 resolver problems" -> runs gqllint scan src/resolvers/
• "Find query depth vulnerabilities" -> runs gqllint scan src/
• "Audit my GraphQL schema" -> runs gqllint scan .
• "Check for introspection leaks" -> runs gqllint scan .

Pro Tier ($19/user/month -- requires GQLLINT_LICENSE_KEY)

gqllint scan --tier pro [file|directory]

Extended scan with 60 patterns covering depth, N+1, fetching, and auth issues.

How to execute:

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [target] --tier pro

What it does:

1. Validates Pro+ license
2. Runs 60 GraphQL patterns (QD, RN, OF, RL categories)
3. Detects over/under fetching and missing pagination
4. Identifies auth gaps, rate limiting issues, and open playgrounds
5. Full category breakdown reporting

gqllint scan --format json [directory]

Generate JSON output for CI/CD integration.

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [directory] --format json

gqllint scan --format html [directory]

Generate HTML report for browser viewing.

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [directory] --format html

gqllint scan --category RN [directory]

Filter scan to a specific check category (QD, RN, OF, RL, SD, CQ).

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [directory] --category RN

Team Tier ($39/user/month -- requires GQLLINT_LICENSE_KEY with team tier)

gqllint scan --tier team [directory]

Full scan with all 90 patterns across all 6 categories including schema design and client safety.

How to execute:

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [directory] --tier team

What it does:

1. Validates Team+ license
2. Runs all 90 patterns across 6 categories
3. Includes schema design checks (input types, naming, JSON scalars, deprecation)
4. Includes client query safety (injection, error handling, caching, codegen)
5. Full category breakdown with per-file results

gqllint scan --verbose [directory]

Verbose output showing every matched line and pattern details.

bash "<SKILL_DIR>/scripts/dispatcher.sh" --path [directory] --verbose

gqllint status

Show license and configuration information.

bash "<SKILL_DIR>/scripts/dispatcher.sh" status

gqllint patterns

List all available detection patterns with IDs, severities, and descriptions.

bash "<SKILL_DIR>/scripts/dispatcher.sh" patterns

Check Categories

GQLLint detects 90 GraphQL anti-patterns across 6 categories:

| Category | Code | Patterns | Description | Severity Range |

|----------|------|----------|-------------|----------------|

| Query Depth & Complexity | QD | 15 | Unbounded depth, no complexity limit, introspection leak, recursive fragments | low -- critical |

| Resolver N+1 | RN | 15 | Database calls in loops, no DataLoader, sequential awaits, missing batching | low -- critical |

| Over/Under Fetching | OF | 15 | SELECT *, no pagination, eager loading, missing projections, full object returns | low -- critical |

| Rate Limiting & Auth | RL | 15 | No auth on mutations, open playground, missing rate limit, no CORS, no persisted queries | low -- critical |

| Schema Design | SD | 15 | Raw scalars in mutations, no input types, JSON scalar, naming issues, no deprecation | low -- high |

| Client Query Safety | CQ | 15 | String concatenation, template injection, no error handling, missing variables, no codegen | low -- critical |

Tier-Based Pattern Access

| Tier | Patterns | Categories |

|------|----------|------------|

| Free | 30 | QD, RN |

| Pro | 60 | QD, RN, OF, RL |

| Team | 90 | QD, RN, OF, RL, SD, CQ |

| Enterprise | 90 | QD, RN, OF, RL, SD, CQ + priority support |

Scoring

GQLLint uses a deductive scoring system starting at 100 (perfect):

| Severity | Point Deduction | Description |

|----------|-----------------|-------------|

| Critical | -25 per finding | Severe risk (query injection, N+1 loops, introspection leak, unauth mutations) |

| High | -15 per finding | Significant problem (no depth limit, no pagination, open playground, resolver waterfalls) |

| Medium | -8 per finding | Moderate concern (schema design gaps, missing rate limits, over-fetching) |

| Low | -3 per finding | Informational / best practice suggestion |

Grading Scale

| Grade | Score Range | Meaning |

|-------|-------------|---------|

| A | 90-100 | Excellent GraphQL quality |

| B | 80-89 | Good GraphQL with minor issues |

| C | 70-79 | Acceptable but needs improvement |

| D | 60-69 | Poor GraphQL quality |

| F | Below 60 | Critical GraphQL problems |

• Pass threshold: 70 (Grade C or better)
• Exit code 0 = pass (score >= 70)
• Exit code 1 = fail (score < 70)

Configuration

Users can configure GQLLint in ~/.openclaw/openclaw.json:

{
  "skills": {
    "entries": {
      "gqllint": {
        "enabled": true,
        "apiKey": "YOUR_LICENSE_KEY_HERE",
        "config": {
          "severityThreshold": "medium",
          "ignorePatterns": ["**/test/**", "**/fixtures/**", "**/*.test.*"],
          "ignoreChecks": [],
          "reportFormat": "text"
        }
      }
    }
  }
}

Important Notes

• Free tier works immediately with no configuration
• All scanning happens locally -- no code is sent to external servers
• License validation is offline -- no phone-home or network calls
• Pattern matching only -- no AST parsing, no external dependencies beyond bash
• Supports scanning all file types in a single pass
• Git hooks use lefthook which must be installed (see install metadata above)
• Exit codes: 0 = pass (score >= 70), 1 = fail (for CI/CD integration)
• Output formats: text (default), json, html

Error Handling

• If lefthook is not installed and user tries hooks, prompt to install it
• If license key is invalid or expired, show clear message with link to https://gqllint.pages.dev/renew
• If a file is binary, skip it automatically with no warning
• If no scannable files found in target, report clean scan with info message
• If an invalid category is specified with --category, show available categories

When to Use GQLLint

The user might say things like:

• "Scan my code for GraphQL issues"
• "Check my resolvers for N+1 problems"
• "Find query depth vulnerabilities"
• "Detect over-fetching in my GraphQL API"
• "Are there any auth gaps in my GraphQL schema?"
• "Check if introspection is enabled in production"
• "Audit my GraphQL schema design"
• "Find security issues in my GraphQL setup"
• "Check for query injection vulnerabilities"
• "Scan for missing pagination on list fields"
• "Run a GraphQL quality audit"
• "Generate a GraphQL health report"
• "Check if my resolvers use DataLoader"
• "Find N+1 database query patterns"
• "Check my client code for unsafe GraphQL patterns"