npm package: @involvex/validator
Description: A comprehensive CLI tool to validate, lint, and fix JSON, YAML, TOML, XML, INI, and JavaScript/TypeScript files
Author: Involvex
Latest version: 1.0.0

# @involvex/validator

A comprehensive, production-ready Node.js CLI tool that validates, lints, and automatically fixes various file types including JSON, YAML, TOML, XML, INI, and JavaScript/TypeScript.

## Features

- **Multi-format support**: JSON, JSONC, YAML, TOML, XML, INI, JavaScript, TypeScript
- **Glob pattern matching**: Target multiple files with flexible patterns
- **Automatic fixing**: Fix common issues automatically
- **Dry-run mode**: Preview changes without writing to disk
- **Verbose logging**: Detailed validation errors with line numbers and context
- **CI/CD ready**: Appropriate exit codes for pipeline integration
- **Modular architecture**: Easy to add new file parsers
- **Prettier integration**: Global formatting consistency
- **ESLint integration**: Linting for JS/TS files

## Installation

```bash
# Install dependencies
bun install

# Build the project
bun run build
```

## Supported File Types

| Format | Extensions                                   |
| ------ | -------------------------------------------- |
| JSON   | `.json`, `.jsonc`                            |
| YAML   | `.yaml`, `.yml`                              |
| TOML   | `.toml`                                      |
| XML    | `.xml`                                       |
| INI    | `.ini`, `.cfg`, `.conf`, `.properties`       |
| JS/TS  | `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs` |

## Usage

### Validate Files

Validate files for syntax and structural issues:

```bash
# Validate all JSON files
validator validate "**/*.json"

# Validate multiple file types
validator validate "**/*.json" "**/*.yaml" "**/*.toml"

# Validate with verbose output
validator validate "**/*.json" --verbose

# Validate with custom Prettier config
validator validate "**/*.json" --prettier .prettierrc.json

# Validate ignoring specific patterns
validator validate "**/*.json" --ignore "node_modules/**" "dist/**"
```

### Fix Files

Validate and automatically fix issues:

```bash
# Fix all JSON files
validator fix "**/*.json"

# Fix with dry-run (preview changes)
validator fix "**/*.json" --dry-run

# Fix with verbose output
validator fix "**/*.json" --verbose

# Fix multiple file types
validator fix "**/*.{js,ts,json,yaml}"
```

### Check Files (CI/CD)

Validate files and exit with non-zero status if issues found:

```bash
# Exit 1 if any errors found (useful for CI/CD)
validator check "**/*.json"

# Check with verbose output
validator check "**/*.json" "**/*.ts" --verbose

# Use in package.json scripts
{
  "scripts": {
    "validate:config": "validator check \"**/*.json\" \"**/*.yaml\""
  }
}
```

### Format Files

Format files using Prettier (without validation):

```bash
# Format files
validator format "**/*.json"

# Format with dry-run
validator format "**/*.json" --dry-run
```

### List Supported File Types

```bash
validator list
```

## Options

### Global Options

| Option                | Description                               |
| --------------------- | ----------------------------------------- |
| `-v, --verbose`       | Output detailed validation information    |
| `--prettier <path>`   | Path to custom Prettier config file       |
| `--eslint <path>`     | Path to custom ESLint config file         |
| `--ignore <patterns>` | Glob patterns to ignore (comma-separated) |

### Command Options

#### validate

```bash
validator validate <patterns...> [options]
```

#### fix

```bash
validator fix <patterns...> [options]
```

| Option          | Description                             |
| --------------- | --------------------------------------- |
| `-d, --dry-run` | Preview changes without writing to disk |

#### check

```bash
validator check <patterns...> [options]
```

#### format

```bash
validator format <patterns...> [options]
```

| Option          | Description                             |
| --------------- | --------------------------------------- |
| `-d, --dry-run` | Preview changes without writing to disk |

## Exit Codes

| Code | Description                     |
| ---- | ------------------------------- |
| 0    | Success - all files valid       |
| 1    | Errors found in validation      |
| 2    | Internal error during execution |

## Examples

### CI/CD Integration

```yaml
# GitHub Actions
- name: Validate config files
  run: bun run build && node dist/index.js check "**/*.json" "**/*.yaml"

- name: Fix formatting issues
  run: bun run build && node dist/index.js fix "**/*.json" --dry-run
```

```json
// package.json
{
  "scripts": {
    "validate": "validator check \"**/*.json\" \"**/*.yaml\" \"**/*.toml\"",
    "validate:verbose": "validator check \"**/*.{json,yaml,toml,xml,ini}\" --verbose",
    "fix": "validator fix \"**/*.{json,yaml,toml}\"",
    "fix:check": "validator fix \"**/*.{json,yaml,toml}\" --dry-run"
  }
}
```

### Common Patterns

```bash
# All config files in a specific directory
validator validate "config/*.{json,yaml,toml}"

# Recursively find all config files
validator check "**/*.json"

# All TypeScript and JavaScript files
validator fix "**/*.{ts,js}"

# Ignore node_modules and dist
validator validate "**/*.json" --ignore "node_modules/**" "dist/**"
```

## Architecture

The tool is built with a modular architecture:

```
src/
├── cli/
│   └── index.ts          # CLI entry point (Commander.js)
├── parsers/
│   ├── index.ts          # Parser registry
│   ├── base.ts           # Base parser class
│   ├── json.ts           # JSON parser
│   ├── yaml.ts           # YAML parser
│   ├── toml.ts           # TOML parser
│   ├── xml.ts            # XML parser
│   ├── ini.ts            # INI parser
│   └── javascript.ts     # JS/TS parser (ESLint)
├── types/
│   └── index.ts          # TypeScript interfaces
└── validator.ts          # Core validation logic
```

### Adding New Parsers

To add support for a new file format:

1. Create a new parser class extending `BaseParser`
2. Implement the `validate` and `fix` methods
3. Register the parser in [`ParserRegistry`](src/parsers/index.ts)

Example:

```typescript
import { BaseParser } from './base.js';

export class CustomParser extends BaseParser {
  extensions = ['.custom'];
  name = 'Custom';

  async validate(filePath: string, content: string): Promise<ValidationResult> {
    // Your validation logic
    return this.createResult(filePath, true, [], [], false);
  }

  async fix(
    filePath: string,
    content: string
  ): Promise<{ fixed: string; result: ValidationResult }> {
    // Your fixing logic
    return { fixed: content, result: await this.validate(filePath, content) };
  }
}
```

## Development

```bash
# Install dependencies
bun install

# Run in development mode
bun run dev

# Run type checking
bun run typecheck

# Run linting
bun run lint

# Auto-fix linting issues
bun run lint:fix

# Format code
bun run format

# Check formatting
bun run format:check

# Build for production
bun run build

# Clean build artifacts
bun run clean
```

## Configuration

### Prettier

Create a `.prettierrc.json` file in your project root:

```json
{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 100
}
```

### ESLint

Create an `.eslintrc.json` file in your project root:

```json
{
  "root": true,
  "env": { "node": true, "es2022": true },
  "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
  "parser": "@typescript-eslint/parser",
  "parserOptions": { "ecmaVersion": "latest", "sourceType": "module" }
}
```

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For issues and questions, please open an issue on the GitHub repository.