GQLLint -- GraphQL Anti-Pattern & Security Analyzer

intent

gqllint scans GraphQL codebases for 90 anti-patterns across 6 categories: query depth/complexity issues, resolver N+1 problems, over/under fetching, rate limiting and auth gaps, schema design flaws, and client query safety problems. use it when auditing a GraphQL codebase for quality, security, and performance issues. produces a markdown/json/html report with severity-graded findings and a 0-100 quality score. all scanning runs locally with zero telemetry.

inputs

required binaries:

• git
• bash
• python3
• jq

required installations:

• lefthook (brew formula, manages git hooks). install with: brew install lefthook

environment variables:

• GQLLINT_LICENSE_KEY: optional. enables pro (60 patterns) or team (90 patterns) tier. not required for free tier (30 patterns).

configuration file (optional):

• ~/.openclaw/openclaw.json: user config with severity threshold, ignore patterns, ignored checks, and report format preference.

external connection:

• gqllint.pages.dev (https): only used for license renewal links (no telemetry, no code upload). license validation is offline.

scanning target:

• file path or directory. gqllint discovers source files and skips .git, node_modules, binaries, images, .min.js files automatically.

procedure

base scan (free tier, all users)

1. accept input: receive file path or directory argument. default to current directory if none provided.
2. validate binaries: check that git, bash, python3, jq are available in PATH. fail with clear message if any missing.
3. discover files: recursively find all source files in target directory. skip .git/, node_modules/, binary files, image files, .min.js files. output file count to stderr.
4. read config: load ~/.openclaw/openclaw.json if present. extract severityThreshold (default: low), ignorePatterns, ignoreChecks, reportFormat (default: text).
5. apply ignores: filter discovered files against ignorePatterns and ignoreChecks from config.
6. run pattern matching: execute regex-based pattern matching against first 30 patterns (free tier limit) in QD and RN categories. for each file, iterate line by line. match each pattern. record: file path, line number, pattern ID, severity, description, recommendation.
7. calculate score: start with 100. for each finding, deduct: critical (-25), high (-15), medium (-8), low (-3). clamp to 0 minimum. final score = max(0, 100 - total_deductions).
8. assign grade: map score to grade: A (90-100), B (80-89), C (70-79), D (60-69), F (<60).
9. output report: generate report in chosen format (text/json/html). include: per-file results with line numbers and findings, overall score, overall grade, category breakdown (patterns matched per category), pass/fail status.
10. exit: return exit code 0 if score >= 70 (pass), exit code 1 if score < 70 (fail). output to stdout (or file if html).

pro tier scan (with valid GQLLINT_LICENSE_KEY)

1. validate license: read GQLLINT_LICENSE_KEY env var. verify it matches pro or team tier signature (offline validation only, no network call). if invalid or expired, output clear message with link to https://gqllint.pages.dev/renew and exit code 1.
2. discover files: (same as step 3 above)
3. read config: (same as step 4 above)
4. apply ignores: (same as step 5 above)
5. run pattern matching: execute regex-based pattern matching against first 60 patterns (pro tier limit) across QD, RN, OF, RL categories. include checks for over/under fetching, missing pagination, auth gaps, rate limiting issues, open playgrounds, persisted queries.
6. calculate score, grade, output: (same as steps 7-10 above, but with 60 patterns)

team tier scan (with valid GQLLINT_LICENSE_KEY at team level)

1. validate license: read GQLLINT_LICENSE_KEY env var. verify it matches team tier signature (offline validation only). if invalid or expired, output clear error and exit code 1.
2. discover files: (same as step 3 above)
3. read config: (same as step 4 above)
4. apply ignores: (same as step 5 above)
5. run pattern matching: execute all 90 patterns across all 6 categories: QD, RN, OF, RL, SD, CQ. include schema design checks (input types, naming, json scalars, deprecation) and client query safety checks (string concatenation, template injection, error handling, variables, codegen).
6. calculate score, grade, output: (same as steps 7-10 above, but with 90 patterns)

category filter scan

1. accept category: receive --category flag with value from {QD, RN, OF, RL, SD, CQ}.
2. validate category: if category not recognized, output available categories and exit code 1.
3. (rest of procedure): run scan as above but match only patterns in specified category. adjust tier access (e.g., free tier cannot access OF, RL, SD, CQ patterns).

json output

1. (run scan as above)
2. format json: convert findings to JSON array. each finding: {file, line, patternId, severity, description, recommendation}. include metadata: {overall_score, grade, category_breakdown, tier, timestamp}.
3. output to stdout or file: write json to stdout (or file if --output specified). exit code 0 if score >= 70, else 1.

html output

1. (run scan as above)
2. format html: generate standalone html report with embedded css. include: header with overall score/grade, findings table (file, line, pattern id, severity, description), per-file breakdown chart, category breakdown chart.
3. output to file: write html to file (default: gqllint-report.html in current directory, or --output path). exit code 0 if score >= 70, else 1.

verbose mode

1. (run scan as above)
2. verbose output: for each matched pattern, output: matched line text, full pattern regex, pattern id, severity, category, description, recommendation. increase verbosity in text format.
3. output report: generate text report with verbose details. exit code 0 if score >= 70, else 1.

status check

1. read license key: check GQLLINT_LICENSE_KEY env var.
2. validate license: offline check. if present, determine tier (pro or team) and expiration date (if any).
3. read config: load ~/.openclaw/openclaw.json if present.
4. output status: display: license key (masked), tier, expiration (if applicable), current config (severity threshold, ignore patterns count, ignore checks count, report format).
5. exit: return exit code 0.

patterns list

1. load all patterns: retrieve all 90 pattern definitions.
2. output patterns: list each pattern with: ID, category, severity, description, remediation guidance.
3. group by category: organize output by QD, RN, OF, RL, SD, CQ.
4. tier note: indicate which patterns are free/pro/team.
5. exit: return exit code 0.

decision points

if no target path provided: use current directory (.).

if target is a file: scan only that file.

if target is a directory: recursively discover and scan all files.

if license key is not set: run free tier scan (30 patterns, QD + RN only).

if license key is set but invalid/expired: output error message with renewal link and exit code 1. do not fall back to free tier.

if --tier pro is specified but license is free: output error message stating pro tier requires valid pro license key and exit code 1.

if --tier team is specified but license is pro: output error message stating team tier requires valid team license key and exit code 1.

if --category is specified but requires higher tier than user has: output error message stating category requires higher tier and exit code 1.

if no scannable files are found in target: report clean scan with info message "no graphql files found" and exit code 0.

if a file is binary: skip it silently (no warning).

if lefthook is not installed and user has git hooks configured: prompt to install lefthook with brew install lefthook and exit code 1.

if config file has ignorePatterns that match all discovered files: report clean scan and exit code 0.

if a pattern match fails due to regex error: log error to stderr (do not crash), skip that pattern, continue scanning.

if score calculation results in negative value: clamp to 0.

if no findings are present: assign score 100, grade A, output pass message and exit code 0.

output contract

text format (default):

• stdout: human-readable report with header (overall score, grade, pass/fail), per-file findings (file path, line number, pattern id, severity, description, recommendation), category breakdown (count of patterns matched per category), footer (total findings count).
• file location: stdout unless --output specified.

json format:

• stdout: json object with keys: {overall_score (number), grade (string), pass (boolean), tier (string), timestamp (iso-8601), findings (array of objects), category_breakdown (object)}.
• each finding object: {file (string), line (number), patternId (string), severity (string), description (string), recommendation (string)}.
• file location: stdout unless --output specified.

html format:

• file: gqllint-report.html (or custom path if --output specified).
• contents: standalone html with embedded css, header with title/score/grade, findings table (sortable by severity), per-file bar chart, category breakdown pie chart, footer with scan timestamp.

markdown report (optional, legacy):

• file location: gqllint-report.md (if --format markdown specified).
• contents: markdown formatted findings with sections per category, remediation guidance links.

scoring metadata:

• overall_score: 0-100 (integer).
• grade: A, B, C, D, or F (string).
• pass: true if score >= 70, false otherwise (boolean).
• per-file scores: each file receives its own score based on its findings.
• category breakdown: count of critical/high/medium/low findings per category.

file discovery log:

• stderr: number of files discovered, number of files scanned, number of files skipped (with reason if verbose).

exit code:

• 0: scan completed successfully, score >= 70 (pass).
• 1: scan completed with score < 70 (fail), or error occurred (license invalid, binary missing, etc.).

outcome signal

user knows the skill worked if:

1. scan completes: output appears in terminal (or file if html/json) with no crash.
2. score is displayed: user sees "overall score: 85/100" or similar at top of report.
3. grade is clear: user sees "grade: B" or similar.
4. pass/fail is unambiguous: user sees "pass" (green, exit code 0) or "fail" (red, exit code 1).
5. findings are actionable: each finding lists line number, pattern id, severity, description, and remediation guidance.
6. category breakdown is visible: user can see how many issues are in query depth vs resolver n+1 vs over-fetching etc.
7. no telemetry occurred: user can confirm via firewall logs or network monitor that no code was uploaded anywhere.
8. exit code matches result: echo $? shows 0 for pass, 1 for fail.
9. html report is readable: if html output chosen, report opens in browser and is fully styled with interactive elements.
10. json is valid: if json output chosen, output can be piped to jq without error.