Przejdź do treści
Biblioteka skilli
Programowanie · Testowanie

graphql-inspector-validate

/graphql-inspector-validate

Waliduje operacje i dokumenty GraphQL względem schematu oraz sprawdza głębokość zapytań, złożoność i użycie fragmentów.

Repozytorium
han ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
08.09.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 08.09.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Waliduje operacje i dokumenty GraphQL względem schematu oraz sprawdza głębokość zapytań, złożoność i użycie fragmentów.

Oryginalny opis (EN)

Use when validating GraphQL operations/documents against a schema, checking query depth, complexity, or fragment usage.

Jak działa

  1. Overview
  2. Core Commands
  3. Validation Rules
  4. Configuration File
  5. Common Validation Errors
  6. CI/CD Integration
  7. Extracting Operations from Code
  8. Best Practices
  9. Common Patterns
  10. Troubleshooting
Sekcje z nagłówków SKILL.md, w oryginale · 363 linii, 1 005 słów
Podgląd SKILL.md
---
name: graphql-inspector-validate
user-invocable: false
description: Use when validating GraphQL operations/documents against a schema, checking query depth, complexity, or fragment usage.
allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
---

# GraphQL Inspector - Validate

Expert knowledge of GraphQL Inspector's validate command for checking operations and documents against a schema with configurable rules.

## Overview

The validate command checks GraphQL operations (queries, mutations, subscriptions) and fragments against a schema. It catches errors like undefined fields, wrong argument types, and invalid fragment spreads before runtime.

## Core Commands

### Basic Validation

```bash
# Validate operations against schema
npx @graphql-inspector/cli validate './src/**/*.graphql' './schema.graphql'

# Validate operations from TypeScript files
npx @graphql-inspector/cli validate './src/**/*.tsx' './schema.graphql'

# Validate with glob patterns
npx @graphql-inspector/cli validate './**/*.{graphql,gql}' './schema.graphql'
```

### Federation Support

```bash
# Apollo Federation V1
npx @graphql-inspector/cli validate './operations/**/*.graphql' './schema.graphql' \
  --federation

# Apollo Federation V2
npx @graphql-inspector/cli validate './operations/**/*.graphql' './schema.graphql' \
  --federationV2

# AWS AppSync directives
npx @graphql-inspector/cli validate './operations/**/*.graphql' './schema.graphql' \
  --aws
```

## Validation Rules

### Depth Limiting

Prevent deeply nested queries that could cause performance issues:

```bash
# Fail if query depth exceeds 10
npx @graphql-inspector/cli validate './src/**/*.graphql' './schema.graphql' \
  --maxDepth 10
```

Example violation:

```graphql
# Depth of 8 - might exceed limit
query DeepQuery {
  user {                     # 1
    posts {                  # 2
      author {               # 3
        followers {          # 4
          posts {            # 5
            comments {       # 6
              author {       # 7
                name         # 8
              }
            }
          }
        }
      }
    }
  }
}
```

### Alias Count

Limit alias usage to prevent response explosion:

```bash
# Max 5 aliases per operation
npx @graphql-inspector/cli validate './src/**/*.graphql' './schema.graphql' \
  --maxAliasCount 5
```

Example violation:

```graphql
# 6 aliases - exceeds limit of 5
query TooManyAliases {
  user1: user(id: "1") { name }
  user2: user(id: "2") { name }
  user3: user(id: "3") { name }
  user4: user(id: "4") { name }
  user5: user(id: "5") { name }
  user6: user(id: "6") { name }  # Exceeds limit
}
```

### Directive Count

Limit directives to prevent abuse:

```bash
# Max 10 directives per operation
npx @graphql-inspector/cli validate './src/**/*.graphql' './schema.graphql' \
  --maxDirectiveCount 10
```

### Token Count

Limit query complexity by token count:

```bash
# Max 1000 tokens per operation
npx @graphql-inspector/cli validate './src/**/*.graphql' './schema.graphql' \
  --maxTokenCount 1000
```

### Complexity Score

Calculate and limit query complexity:

```bash
# Max complexity score of 100
npx @graphql-inspector/cli validate './src/**/*.graphql' './schema.graphql' \
  --maxComplexityScore 100
```

## Configuration File

Create `.graphql-inspector.yaml`:

```yaml
validate:
  schema: './schema.graphql'
  documents: './src/**/*.graphql'

  # Validation limits
  maxDepth: 10
  maxAliasCount: 5
  maxDirectiveCount: 10
  maxTokenCount: 1000
  maxComplexityScore: 100

  # Federation support
  federation: false
  federationV2: false
  aws: false
```

## Common Validation Errors

### Unknown Field

```
Error: Cannot query field "unknownField" on type "User".
```

Fix: Check field name spelling or add field to schema.

### Wrong Argument Type

```
Error: Argument "id" has invalid value "123".
Expected type "ID!", found "123" (String).
```

Fix: Use correct type for argument.

### Missing Required Argument

```
Error: Field "user" argument "id" of type "ID!" is required.
```

Fix: Provide required argument.

### Invalid Fragment Spread

```
Error: Fragment "UserFields" cannot be spread here as objects of
type "Post" can never be of type "User".
```

Fix: Ensure fragment type matches spread location.

### Unused Fragment

```
Warning: Fragment "UnusedFragment" is never used.
```

Fix: Remove or use the fragment.

## CI/CD Integration

### GitHub Actions

```yaml
name: Validate Operations
user-invocable: false
on:
  pull_request:
    paths:
      - 'src/**/*.graphql'
      - 'src/**/*.tsx'
      - 'schema.graphql'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Inspector
        run: npm install -g @graphql-inspector/cli

      - name: Validate operations
        run: |
          graphql-inspector validate \
            'src/**/*.graphql' \
            schema.graphql \
            --maxDepth 10 \
            --maxAliasCount 5
```

### Pre-commit Hook

```json
{
  "husky": {
    "hooks": {
      "pre-commit": "graphql-inspector validate 'src/**/*.graphql' schema.graphql"
    }
  }
}
```

## Extracting Operations from Code

GraphQL Inspector can extract operations from various file types:

### TypeScript/JavaScript

```typescript
// Operations in template literals are detected
const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      name
      email
    }
  }
`;
```

### React with GraphQL

```tsx
// Tagged template literals in React files
import { gql } from '@apollo/client';

const USER_QUERY = gql`
  query UserQuery {
    currentUser {
      id
      name
    }
  }
`;
```

## Best Practices

1. **Validate in CI** - Run validation on every PR affecting GraphQL files
2. **Set reasonable limits** - Start with permissive limits, tighten over time
3. **Validate against production schema** - Ensure operations work in production
4. **Extract operations from code** - Validate all operations, not just `.graphql` files
5. **Use Federation flags** - Enable if using Apollo Federation
6. **Fail on warnings** - Treat unused fragments as errors in CI
7. **Version your schema** - Validate against specific schema versions
8. **Document limits** - Explain why limits exist to developers

## Common Patterns

### Multi-Schema Validation

For monorepos with multiple schemas:

```bash
# Validate against specific service schema
npx @graphql-inspector/cli validate \
  './packages/app/src/**/*.graphql' \
  './packages/api/schema.graphql'

# Validate against federated supergraph
npx @graphql-inspector/cli validate \
  './packages/web/src/**/*.graphql' \
  './supergraph.graphql' \
  --federationV2
```

### Incremental Adoption

Start permissive, add stricter rules over time:

```yaml
# Phase 1: Basic validation only
validate:
  schema: './schema.graphql'
  documents: './src/**/*.graphql'

# Phase 2: Add depth limiting
validate:
  schema: './schema.graphql'
  documents: './src/**/*.graphql'
  maxDepth: 15

# Phase 3: Add complexity limits
validate:
  schema: './schema.graphql'
  documents: './src/**/*.graphql'
  maxDepth: 10
  maxAliasCount: 10
  maxComplexityScore: 200
```

## Troubleshooting

### "Schema file not found"

- Verify schema path is correct
- Check glob pattern matches schema location
- Use absolute path if relative fails

### "No documents found"

- Check glob pattern matches operation files
- Verify file extensions are correct
- Ensure files contain GraphQL operations

### "Unknown directive"

- Add `--federation` or `--federationV2` for Federation directives
- Add `--aws` for AppSync directives
- Check custom directives are defined in schema

### Operations not detected in code

- Ensure using tagged template literal (`gql\`...\``)
- Check file extension is included in glob
- Verify GraphQL Inspector can parse the file type

## When to Use This Skill

- Setting up operation validation in CI/CD
- Enforcing query complexity limits
- Validating operations before deployment
- Catching schema-operation mismatches early
- Preventing deeply nested queries
- Auditing existing operations for compliance

Wersje

W bazie nie ma innych skilli o nazwie graphql-inspector-validate.

Migawka bazy z 13.11.2026 · wersja paczki 04badea90867 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100graphql-inspector-audit
    Audytuje operacje GraphQL pod kątem metryk złożoności, głębokości zapytań, użycia dyrektyw i problemów z wydajnością zapytań.
  • 100graphql-inspector-diff
    Wykrywa zmiany łamiące zgodność między wersjami schematu GraphQL, porównuje schematy z różnych gałęzi i waliduje migracje schematu.
  • 100validating-api-schemas
    Waliduje schematy API względem specyfikacji OpenAPI, JSON Schema i GraphQL.
  • 100validating-api-schemas
    Waliduje schematy API względem specyfikacji OpenAPI, JSON Schema i GraphQL.
  • 100graphql-schema-regression
    Porównuje dwa schematy GraphQL przez graphql-inspector diff, klasyfikuje zmiany jako BREAKING, DANGEROUS lub NON_BREAKING i bramkuje CI na regresjach schematu.
  • 92write-script-graphql
    Prowadzi przez pisanie zapytań GraphQL zgodnie z konwencjami tej platformy.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.