# GraphQL Lint Unused Fields

🚀 **Terminal and Pipeline Tool** for detecting unused fields in GraphQL queries - **Open source core** + **Specific extensions**.

[![npm version](https://badge.fury.io/js/graphql-lint-unused-fields.svg)](https://badge.fury.io/js/graphql-lint-unused-fields)

## 📦 Installation

```bash
npm install graphql-lint-unused-fields
```

## 🎯 Features

- ✅ **Traditional GraphQL query detection** (`gql`, `graphql` template literals)
- ✅ **Complete GraphQL alias mapping** 🔗
- ✅ **Field usage analysis** in TypeScript/JavaScript
- ✅ **React support** (JSX, hooks, destructuring)
- ✅ **Cross-file analysis** for tracking between files
- ✅ **Integrated CLI** for CI/CD usage
- ✅ **Configurable pipeline** with customizable steps
- ✅ **Multiple output formats** (console, json, eslint)
- ✅ **Configuration via file** (JSON/YAML)

## 🚀 Basic Usage

### CLI

```bash
# Basic usage
npx graphql-lint-unused-fields /path/to/project

# Configurable pipeline
npx graphql-lint-pipeline /path/to/project --format console,json --parallel

# With configuration file
npx graphql-lint-pipeline --config pipeline-config.json
```

### Programmatic

```typescript
import { UnusedFieldsLinter } from "graphql-lint-unused-fields";

const linter = new UnusedFieldsLinter();
const result = await linter.analyze("/path/to/project");

console.log(`Unused fields: ${result.unusedFields.length}`);
```

## 🎛️ CLI Options

```bash
# Basic analysis
npx graphql-lint-unused-fields /project

# Deep scan (more files)
npx graphql-lint-unused-fields /project --deep-scan

# No file limit
npx graphql-lint-unused-fields /project --no-limit

# Advanced analysis
npx graphql-lint-unused-fields /project --advanced

# Pipeline with multiple formats
npx graphql-lint-pipeline /project --format console,json --parallel
```

## 🔧 Configuration

Create a `graphql-lint.config.js` file:

```javascript
module.exports = {
  // File patterns to include
  include: ["src/**/*.{ts,tsx,js,jsx}"],

  // Patterns to exclude
  exclude: ["node_modules/**", "**/*.test.*"],

  // Advanced analysis
  advanced: true,

  // File limit (0 = no limit)
  maxFiles: 1000,
};
```

## 📊 Example Output

```
🔍 GRAPHQL LINT - ANALYSIS RESULT

📊 GENERAL STATISTICS:
   🎯 Queries analyzed: 42
   📋 Fields found: 156
   ✅ Fields in use: 142 (91%)
   ❌ Unused fields: 14 (9%)

🚨 These are the unused fields in your GraphQL queries:

🔹 GetUser (3 unused fields) [/path/to/file.ts]
   • email (line 15:10)
     📁 File: /path/to/file.ts
     Path: user → email
   • phone (line 16:12)
     📁 File: /path/to/file.ts
     Path: user → phone
```

## 🏗️ Monorepo Architecture

This package is part of a monorepo with two main packages:

- **graphql-lint-unused-fields** (this package) - Open source core tool
- **[graphql-lint-unused-fields-clint](https://www.npmjs.com/package/graphql-lint-unused-fields-clint)** - Clint-specific extension

## 🛠️ Extensibility

For custom patterns and Clint-specific analysis, see [graphql-lint-unused-fields-clint](https://www.npmjs.com/package/graphql-lint-unused-fields-clint) which extends this package.

## 📚 Documentation

- 📖 [Core Package README](https://github.com/Regenerating-World/graphql-lint-unused-fields/tree/main/packages/core/README.md)
- 🎯 [Clint Package README](https://github.com/Regenerating-World/graphql-lint-unused-fields/tree/main/packages/clint/README.md)
- ⚙️ [CLI Documentation](https://github.com/Regenerating-World/graphql-lint-unused-fields/tree/main/docs/CLI.md)
- 🔗 [GraphQL Aliases Mapping](https://github.com/Regenerating-World/graphql-lint-unused-fields/tree/main/docs/GRAPHQL_ALIASES.md) ⭐
- 🔌 [ESLint Plugin](https://github.com/Regenerating-World/graphql-lint-unused-fields/tree/main/docs/ESLINT_PLUGIN.md)
- 📡 [Hasura Schema Analysis](https://github.com/Regenerating-World/graphql-lint-unused-fields/tree/main/docs/HASURA_SCHEMA_ANALYSIS.md)
- 🔄 [Variable Tracking](https://github.com/Regenerating-World/graphql-lint-unused-fields/tree/main/docs/VARIABLE_TRACKING.md)
- 🚀 [Pipeline Configuration](https://github.com/Regenerating-World/graphql-lint-unused-fields/tree/main/docs/PIPELINE.md) ⭐

## 🤝 Contributing

Contributions are welcome! See [CONTRIBUTING.md](https://github.com/Regenerating-World/graphql-lint-unused-fields/blob/main/CONTRIBUTING.md) for guidelines.

## 📝 License

MIT - See [LICENSE](https://github.com/Regenerating-World/graphql-lint-unused-fields/blob/main/LICENSE) for details.