@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

# 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:

# 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:

# 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:

# 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):

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

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

List Supported File Types

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

validator validate <patterns...> [options]

fix

validator fix <patterns...> [options]

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

check

validator check <patterns...> [options]

format

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

# 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

// 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

# 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

Example:

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

# 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:

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

ESLint

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

{
  "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.