\r \r

GQLLint -- GraphQL Anti-Pattern & Security Analyzer\r

\r 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.\r \r 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.\r \r

Commands\r

\r

Free Tier (No license required)\r

\r

gqllint scan [file|directory]\r

One-shot GraphQL quality scan of files or directories.\r \r How to execute:\r

bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [target]\r
```\r
\r
**What it does:**\r
1. Accepts a file path or directory (defaults to current directory)\r
2. Discovers all source files (skips .git, node_modules, binaries, images, .min.js)\r
3. Runs 30 GraphQL patterns against each file (free tier limit)\r
4. Calculates a GraphQL quality score (0-100) per file and overall\r
5. Grades: A (90-100), B (80-89), C (70-79), D (60-69), F (\x3C60)\r
6. Outputs findings with: file, line number, check ID, severity, description, recommendation\r
7. Exit code 0 if score >= 70, exit code 1 if GraphQL quality is poor\r
8. Free tier limited to first 30 patterns (QD + RN categories)\r
\r
**Example usage scenarios:**\r
- "Scan my code for GraphQL issues" -> runs `gqllint scan .`\r
- "Check this file for N+1 resolver problems" -> runs `gqllint scan src/resolvers/`\r
- "Find query depth vulnerabilities" -> runs `gqllint scan src/`\r
- "Audit my GraphQL schema" -> runs `gqllint scan .`\r
- "Check for introspection leaks" -> runs `gqllint scan .`\r
\r
### Pro Tier ($19/user/month -- requires GQLLINT_LICENSE_KEY)\r
\r
#### `gqllint scan --tier pro [file|directory]`\r
Extended scan with 60 patterns covering depth, N+1, fetching, and auth issues.\r
\r
**How to execute:**\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [target] --tier pro\r
```\r
\r
**What it does:**\r
1. Validates Pro+ license\r
2. Runs 60 GraphQL patterns (QD, RN, OF, RL categories)\r
3. Detects over/under fetching and missing pagination\r
4. Identifies auth gaps, rate limiting issues, and open playgrounds\r
5. Full category breakdown reporting\r
\r
#### `gqllint scan --format json [directory]`\r
Generate JSON output for CI/CD integration.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [directory] --format json\r
```\r
\r
#### `gqllint scan --format html [directory]`\r
Generate HTML report for browser viewing.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [directory] --format html\r
```\r
\r
#### `gqllint scan --category RN [directory]`\r
Filter scan to a specific check category (QD, RN, OF, RL, SD, CQ).\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [directory] --category RN\r
```\r
\r
### Team Tier ($39/user/month -- requires GQLLINT_LICENSE_KEY with team tier)\r
\r
#### `gqllint scan --tier team [directory]`\r
Full scan with all 90 patterns across all 6 categories including schema design and client safety.\r
\r
**How to execute:**\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [directory] --tier team\r
```\r
\r
**What it does:**\r
1. Validates Team+ license\r
2. Runs all 90 patterns across 6 categories\r
3. Includes schema design checks (input types, naming, JSON scalars, deprecation)\r
4. Includes client query safety (injection, error handling, caching, codegen)\r
5. Full category breakdown with per-file results\r
\r
#### `gqllint scan --verbose [directory]`\r
Verbose output showing every matched line and pattern details.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" --path [directory] --verbose\r
```\r
\r
#### `gqllint status`\r
Show license and configuration information.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" status\r
```\r
\r
#### `gqllint patterns`\r
List all available detection patterns with IDs, severities, and descriptions.\r
\r
```bash\r
bash "\x3CSKILL_DIR>/scripts/dispatcher.sh" patterns\r
```\r
\r
## Check Categories\r
\r
GQLLint detects 90 GraphQL anti-patterns across 6 categories:\r
\r
| Category | Code | Patterns | Description | Severity Range |\r
|----------|------|----------|-------------|----------------|\r
| **Query Depth & Complexity** | QD | 15 | Unbounded depth, no complexity limit, introspection leak, recursive fragments | low -- critical |\r
| **Resolver N+1** | RN | 15 | Database calls in loops, no DataLoader, sequential awaits, missing batching | low -- critical |\r
| **Over/Under Fetching** | OF | 15 | SELECT *, no pagination, eager loading, missing projections, full object returns | low -- critical |\r
| **Rate Limiting & Auth** | RL | 15 | No auth on mutations, open playground, missing rate limit, no CORS, no persisted queries | low -- critical |\r
| **Schema Design** | SD | 15 | Raw scalars in mutations, no input types, JSON scalar, naming issues, no deprecation | low -- high |\r
| **Client Query Safety** | CQ | 15 | String concatenation, template injection, no error handling, missing variables, no codegen | low -- critical |\r
\r
## Tier-Based Pattern Access\r
\r
| Tier | Patterns | Categories |\r
|------|----------|------------|\r
| **Free** | 30 | QD, RN |\r
| **Pro** | 60 | QD, RN, OF, RL |\r
| **Team** | 90 | QD, RN, OF, RL, SD, CQ |\r
| **Enterprise** | 90 | QD, RN, OF, RL, SD, CQ + priority support |\r
\r
## Scoring\r
\r
GQLLint uses a deductive scoring system starting at 100 (perfect):\r
\r
| Severity | Point Deduction | Description |\r
|----------|-----------------|-------------|\r
| **Critical** | -25 per finding | Severe risk (query injection, N+1 loops, introspection leak, unauth mutations) |\r
| **High** | -15 per finding | Significant problem (no depth limit, no pagination, open playground, resolver waterfalls) |\r
| **Medium** | -8 per finding | Moderate concern (schema design gaps, missing rate limits, over-fetching) |\r
| **Low** | -3 per finding | Informational / best practice suggestion |\r
\r
### Grading Scale\r
\r
| Grade | Score Range | Meaning |\r
|-------|-------------|---------|\r
| **A** | 90-100 | Excellent GraphQL quality |\r
| **B** | 80-89 | Good GraphQL with minor issues |\r
| **C** | 70-79 | Acceptable but needs improvement |\r
| **D** | 60-69 | Poor GraphQL quality |\r
| **F** | Below 60 | Critical GraphQL problems |\r
\r
- **Pass threshold:** 70 (Grade C or better)\r
- Exit code 0 = pass (score >= 70)\r
- Exit code 1 = fail (score \x3C 70)\r
\r
## Configuration\r
\r
Users can configure GQLLint in `~/.openclaw/openclaw.json`:\r
\r
```json\r
{\r
  "skills": {\r
    "entries": {\r
      "gqllint": {\r
        "enabled": true,\r
        "apiKey": "YOUR_LICENSE_KEY_HERE",\r
        "config": {\r
          "severityThreshold": "medium",\r
          "ignorePatterns": ["**/test/**", "**/fixtures/**", "**/*.test.*"],\r
          "ignoreChecks": [],\r
          "reportFormat": "text"\r
        }\r
      }\r
    }\r
  }\r
}\r
```\r
\r
## Important Notes\r
\r
- **Free tier** works immediately with no configuration\r
- **All scanning happens locally** -- no code is sent to external servers\r
- **License validation is offline** -- no phone-home or network calls\r
- Pattern matching only -- no AST parsing, no external dependencies beyond bash\r
- Supports scanning all file types in a single pass\r
- Git hooks use **lefthook** which must be installed (see install metadata above)\r
- Exit codes: 0 = pass (score >= 70), 1 = fail (for CI/CD integration)\r
- Output formats: text (default), json, html\r
\r
## Error Handling\r
\r
- If lefthook is not installed and user tries hooks, prompt to install it\r
- If license key is invalid or expired, show clear message with link to https://gqllint.pages.dev/renew\r
- If a file is binary, skip it automatically with no warning\r
- If no scannable files found in target, report clean scan with info message\r
- If an invalid category is specified with --category, show available categories\r
\r
## When to Use GQLLint\r
\r
The user might say things like:\r
- "Scan my code for GraphQL issues"\r
- "Check my resolvers for N+1 problems"\r
- "Find query depth vulnerabilities"\r
- "Detect over-fetching in my GraphQL API"\r
- "Are there any auth gaps in my GraphQL schema?"\r
- "Check if introspection is enabled in production"\r
- "Audit my GraphQL schema design"\r
- "Find security issues in my GraphQL setup"\r
- "Check for query injection vulnerabilities"\r
- "Scan for missing pagination on list fields"\r
- "Run a GraphQL quality audit"\r
- "Generate a GraphQL health report"\r
- "Check if my resolvers use DataLoader"\r
- "Find N+1 database query patterns"\r
- "Check my client code for unsafe GraphQL patterns"\r