Add GraphQL lint with a number of (configurable) rules.

README.md

@@ -31,6 +31,7 @@ A comprehensive VS Code extension for developing GraphQL APIs with StepZen, feat
 - **Auto-completion** - Intelligent suggestions for StepZen directives
 - **Syntax Highlighting** - Enhanced GraphQL syntax support
 - **Schema Validation** - Real-time validation of schema files
+- **GraphQL Linting** - Comprehensive GraphQL schema linting with custom rules
 - **Quick Actions** - Context-aware commands and shortcuts
 
 ## Quick Start
@@ -90,13 +91,43 @@ https://petstore.swagger.io/v2/swagger.json
 - `StepZen: Deploy Schema` - Deploy your schema to StepZen
 - `StepZen: Run GraphQL Request` - Execute GraphQL operations
 - `StepZen: Open Schema Visualizer` - Visualize your schema structure
+- `StepZen: Lint GraphQL Schema` - Lint GraphQL schema files with custom rules
 
 ### Utility Commands
 
 - `StepZen: Generate Operations` - Create sample GraphQL operations
 - `StepZen: Validate Schema` - Check schema for errors
 - `StepZen: Show Logs` - View extension logs and debugging info
 
+## GraphQL Linting
+
+The extension includes comprehensive GraphQL schema linting with custom rules:
+
+### Features
+
+- **Real-time Linting** - Automatically lint GraphQL files as you type (optional)
+- **Comprehensive Rules** - Built-in GraphQL best practices and StepZen-specific rules
+- **VS Code Integration** - Linting errors and warnings appear in the Problems panel
+- **Customizable Rules** - Configure linting rules through VS Code settings
+
+### Configuration
+
+Enable automatic linting in your VS Code settings:
+
+```json
+{
+  "stepzen.autoLintGraphQL": true
+}
+```
+
+### Manual Linting
+
+Use the command palette to manually lint your GraphQL schema:
+
+1. Open Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`)
+2. Run `StepZen: Lint GraphQL Schema`
+3. View results in the Problems panel
+
 ## Import Features
 
 ### Smart cURL Parsing
@@ -135,7 +166,7 @@ The extension follows a layered architecture with clear separation of concerns:
 ```
 Extension Layer (Commands, Panels, Utils)
     ↓
-Service Registry (CLI, Logger, Import, SchemaIndex, Request)
+Service Registry (CLI, Logger, Import, SchemaIndex, Request, GraphQLLinter)
     ↓
 Schema Processing Layer (Indexer, Linker, Parser)
     ↓
@@ -146,6 +177,7 @@ Types (Pure data structures)
 
 - **ImportService** - Handles all import operations with type-specific builders
 - **SchemaIndexService** - Real-time schema analysis and indexing
+- **GraphQLLinterService** - GraphQL schema linting with graphql-eslint
 - **StepzenCliService** - CLI integration and command execution
 - **Logger** - Comprehensive logging and debugging
 - **RequestService** - GraphQL request execution
@@ -159,7 +191,8 @@ Types (Pure data structures)
   "stepzen.cliPath": "/path/to/stepzen",
   "stepzen.logLevel": "info",
   "stepzen.autoValidate": true,
-  "stepzen.defaultWorkingDir": "./stepzen"
+  "stepzen.defaultWorkingDir": "./stepzen",
+  "stepzen.autoLintGraphQL": false
 }
 ```
 
@@ -221,6 +254,12 @@ npm run test:integration   # Integration tests only
 - Check StepZen directive usage
 - Validate file paths and references
 
+**GraphQL Linting Issues**
+
+- Check that GraphQL files have valid syntax
+- Verify VS Code settings are correct
+- Review extension output for error messages
+
 ### Getting Help
 
 - Check the [StepZen Documentation](https://stepzen.com/docs)

docs/graphql-linting.md

@@ -0,0 +1,232 @@
+# GraphQL Linting with Custom Rules
+
+This document describes the custom GraphQL linting implementation in the StepZen VS Code extension, providing comprehensive GraphQL schema validation and linting capabilities.
+
+## Overview
+
+The GraphQL linting feature uses the built-in GraphQL parser to provide real-time validation of GraphQL schema files. This custom implementation helps developers maintain high-quality GraphQL schemas by catching common issues and enforcing best practices without external dependencies.
+
+## Features
+
+### 🎯 **Real-time Linting**
+
+- Automatically lint GraphQL files as you type (configurable)
+- Instant feedback in the VS Code Problems panel
+- Integration with the existing file watching system
+
+### 📋 **Comprehensive Rules**
+
+- **GraphQL Best Practices**: Enforce standard GraphQL conventions
+- **StepZen-Specific Rules**: Customized for StepZen's GraphQL implementation
+- **Customizable Configuration**: Adjust rules through VS Code settings
+
+### 🔧 **VS Code Integration**
+
+- Native VS Code diagnostic collection
+- Problems panel integration
+- Command palette access
+- Progress reporting for long operations
+
+## Architecture
+
+The GraphQL linting feature follows the existing service registry pattern:
+
+```
+GraphQLLinterService
+├── ESLint Integration
+├── VS Code Diagnostics
+├── Configuration Management
+└── File Watching Integration
+```
+
+### Service Integration
+
+```typescript
+// Service registry includes the linter
+export interface ServiceRegistry {
+  // ... other services
+  graphqlLinter: GraphQLLinterService;
+}
+```
+
+### Diagnostic Collection
+
+The linter creates a dedicated VS Code diagnostic collection (`stepzen-graphql-lint`) that displays linting issues in the Problems panel alongside other diagnostics.
+
+## Configuration
+
+### Extension Settings
+
+Configure GraphQL linting behavior through VS Code settings:
+
+```json
+{
+  "stepzen.autoLintGraphQL": false
+}
+```
+
+### Settings Reference
+
+| Setting                   | Type    | Default | Description                           |
+| ------------------------- | ------- | ------- | ------------------------------------- |
+| `stepzen.autoLintGraphQL` | boolean | `false` | Enable automatic linting on file save |
+
+## Available Rules
+
+The custom GraphQL linter includes the following built-in rules:
+
+### Core GraphQL Rules
+
+| Rule                         | Severity | Description                           |
+| ---------------------------- | -------- | ------------------------------------- |
+| `no-anonymous-operations`    | error    | Prevent anonymous GraphQL operations  |
+| `no-duplicate-fields`        | error    | Prevent duplicate field definitions   |
+| `require-description`        | warn     | Require descriptions for types/fields |
+| `require-deprecation-reason` | warn     | Require reason for deprecated fields  |
+
+### Rule Details
+
+- **no-anonymous-operations**: Ensures all GraphQL operations (queries, mutations, subscriptions) have names
+- **no-duplicate-fields**: Prevents duplicate field definitions within the same type
+- **require-description**: Suggests adding descriptions to types and fields for better documentation
+- **require-deprecation-reason**: Ensures deprecated fields include a reason for deprecation
+
+## Usage
+
+### Manual Linting
+
+1. Open Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`)
+2. Run `StepZen: Lint GraphQL Schema`
+3. View results in the Problems panel
+
+### Automatic Linting
+
+Enable automatic linting in settings:
+
+```json
+{
+  "stepzen.autoLintGraphQL": true
+}
+```
+
+Files will be automatically linted when:
+
+- A GraphQL file is saved
+- The file watcher detects changes
+- The project is scanned
+
+### Command Line Integration
+
+The linter integrates with the existing ESLint configuration:
+
+```bash
+# Lint GraphQL files using the extension's configuration
+npm run lint
+```
+
+## Error Handling
+
+### Initialization Errors
+
+If the GraphQL linter fails to initialize:
+
+1. Check that `@graphql-eslint/eslint-plugin` and `@graphql-eslint/parser` are installed
+2. Verify VS Code settings are valid
+3. Check the extension output for detailed error messages
+
+### Linting Errors
+
+Common linting issues and solutions:
+
+| Issue                | Solution                                            |
+| -------------------- | --------------------------------------------------- |
+| Anonymous operations | Add operation names to all queries/mutations        |
+| Missing descriptions | Add descriptions to types and fields                |
+| Duplicate fields     | Remove duplicate field definitions                  |
+| Deprecated fields    | Add deprecation reasons or remove deprecated fields |
+
+## Performance Considerations
+
+### File Watching
+
+The linter integrates with the existing file watching system to minimize performance impact:
+
+- Debounced linting (250ms delay)
+- Only lints changed files when auto-linting is enabled
+- Lazy initialization of ESLint instance
+
+### Memory Management
+
+- ESLint instance is created once and reused
+- Diagnostic collection is properly disposed on extension deactivation
+- File watchers are cleaned up when switching projects
+
+## Testing
+
+### Unit Tests
+
+The GraphQL linter includes comprehensive unit tests:
+
+```bash
+npm run test:unit -- --grep "GraphQL Linter"
+```
+
+### Integration Tests
+
+Test files with intentional linting issues are provided in `src/test/fixtures/schema-sample/test-lint.graphql`.
+
+## Troubleshooting
+
+### Common Issues
+
+**Linter not working**
+
+- Check that the GraphQL parser is working correctly
+- Verify VS Code settings are correct
+- Check extension output for error messages
+
+**False positives**
+
+- Review rule configuration in settings
+- Consider disabling specific rules for your use case
+- Check StepZen-specific rule overrides
+
+**Performance issues**
+
+- Disable auto-linting for large projects
+- Use manual linting instead of automatic
+- Check file watcher configuration
+
+### Debug Mode
+
+Enable debug logging to troubleshoot linting issues:
+
+```json
+{
+  "stepzen.logLevel": "debug"
+}
+```
+
+## Future Enhancements
+
+### Planned Features
+
+- **Fix Suggestions**: Auto-fix capabilities for common issues
+- **Custom Rule Sets**: Predefined rule configurations for different project types
+- **Performance Optimization**: Incremental linting for large schemas
+- **Integration with StepZen CLI**: Use StepZen's validation alongside ESLint
+
+### Contributing
+
+To contribute to the GraphQL linting feature:
+
+1. Follow the existing code patterns and architecture
+2. Add tests for new functionality
+3. Update documentation for new features
+4. Consider performance impact of changes
+
+## References
+
+- [GraphQL Best Practices](https://graphql.org/learn/best-practices/)
+- [StepZen GraphQL Documentation](https://stepzen.com/docs)
+- [VS Code Extension API](https://code.visualstudio.com/api)

package.json

@@ -99,6 +99,16 @@
         "command": "stepzen.generateOperations",
         "title": "Generate Operations from Schema",
         "category": "StepZen"
+      },
+      {
+        "command": "stepzen.lintGraphql",
+        "title": "Lint GraphQL Schema",
+        "category": "StepZen"
+      },
+      {
+        "command": "stepzen.configureLintRules",
+        "title": "Configure GraphQL Lint Rules",
+        "category": "StepZen"
       }
     ],
     "configuration": {
@@ -119,6 +129,55 @@
           "type": "boolean",
           "default": false,
           "description": "When enabled, logs will be written to disk (requires trusted workspace)"
+        },
+        "stepzen.autoLintGraphQL": {
+          "type": "boolean",
+          "default": false,
+          "description": "When enabled, GraphQL files will be automatically linted when saved"
+        },
+        "stepzen.graphqlLintRules": {
+          "type": "object",
+          "default": {
+            "no-anonymous-operations": true,
+            "no-duplicate-fields": true,
+            "require-description": true,
+            "require-deprecation-reason": true,
+            "field-naming-convention": true,
+            "root-fields-nullable": true
+          },
+          "description": "Configure which GraphQL linting rules to enable",
+          "properties": {
+            "no-anonymous-operations": {
+              "type": "boolean",
+              "default": true,
+              "description": "Prevent anonymous GraphQL operations"
+            },
+            "no-duplicate-fields": {
+              "type": "boolean",
+              "default": true,
+              "description": "Prevent duplicate field definitions"
+            },
+            "require-description": {
+              "type": "boolean",
+              "default": true,
+              "description": "Require descriptions for types and fields"
+            },
+            "require-deprecation-reason": {
+              "type": "boolean",
+              "default": true,
+              "description": "Require reason for deprecated fields"
+            },
+            "field-naming-convention": {
+              "type": "boolean",
+              "default": true,
+              "description": "Enforce camelCase for field names"
+            },
+            "root-fields-nullable": {
+              "type": "boolean",
+              "default": true,
+              "description": "Require nullable fields in root operation types"
+            }
+          }
         }
       }
     },