# Flint

> Flint's core innovation is its hybrid architecture that combines TypeScript development ergonomics with native-speed performance.

---

# Flint Architecture

## Source: https://flint.fyi

## Hybrid Linting Architecture

Flint's core innovation is its hybrid architecture that combines TypeScript development ergonomics with native-speed performance.

### The Design Choice

Traditional linters face a fundamental tradeoff:

**JavaScript/TypeScript-based Linters (like ESLint)**
- Pros: Easy to understand, contribute to, and extend
- Cons: Slower performance, especially on large codebases

**Native-Speed Linters (like Biome, Oxlint)**
- Pros: Extremely fast performance
- Cons: Harder for community contributions, steeper learning curve

### Flint's Solution

Flint divides responsibilities between two layers:

#### 1. Core Framework (TypeScript)
- Linter orchestration and rule management
- Configuration handling
- Output formatting
- User interface
- Easy for contributors to write and understand

#### 2. Language Plugins (Flexible Implementation)
- Parsing (can use native implementations like `typescript-go`)
- Type checking
- Other computationally expensive operations
- Can be implemented in native languages for speed
- Maintain a well-defined interface for the core framework

### How It Works

```
User Input
    ↓
TypeScript Core Framework
    ↓
Rule Engine (TypeScript)
    ├─→ Core Rules (TypeScript)
    ├─→ Plugin Rules (TypeScript or Native)
    ├─→ Language Plugins (Native-Speed)
    │   ├─→ Parser (could be native)
    │   └─→ Type Checker (could be native)
    └─→ Output Formatting (TypeScript)
    ↓
Formatted Results
```

### Benefits

1. **Low Barrier to Entry**: New contributors can easily write rules in TypeScript
2. **Extensibility**: Plugin authors can choose their implementation language
3. **Performance**: Heavy lifting delegated to optimized native components
4. **Maintainability**: Clear separation of concerns between framework and plugins
5. **Community-Friendly**: TypeScript core makes it easier to build a contributor base

## Core Concepts

### The Rule System

Rules in Flint are written as TypeScript/JavaScript functions that:
- Access TypeScript's type information
- Check specific code patterns
- Report violations with detailed messages
- Can be configured by users

### Type-Aware Linting

Unlike traditional linters that only understand syntax, Flint leverages TypeScript's type information:
- Rules can understand semantic meaning, not just syntax
- Better error detection and fewer false positives
- Integration with TypeScript's type checker

### Configuration System

Flint's type-safe configuration:
- Written in JavaScript/TypeScript (not JSON)
- Full IDE autocomplete support
- Type validation at configuration time
- Reduces user errors and ambiguity

## Multi-Tier Plugin Organization

### Core Plugins (Built-in)

Shipped with Flint, maintained by core team:
- JSON linting
- Markdown linting
- JavaScript/TypeScript linting
- YAML linting
- Package.json manifest linting

### Focused Plugins

Maintained by dedicated teams, focused on specific areas:
- Browser-specific rules
- Node.js-specific rules
- React-specific rules
- Performance-specific rules
- And more

### Incubator Plugins

Community-maintained plugins for emerging needs:
- Framework-specific rules (Next.js, Nuxt, Astro)
- Specialized domain rules (Vitest, SolidJS)

## Performance Optimizations

### Type-Aware Caching

Flint implements intelligent caching:
- Caches type information across runs
- Avoids re-type-checking unchanged files
- Significantly improves performance on large codebases
- Especially beneficial in watch mode and CI environments

### Parallel Processing

- File linting can happen in parallel
- Plugin operations optimized for concurrent execution
- Efficient resource utilization

### Incremental Updates

- Only re-lint changed files
- Maintain state between runs
- Fast feedback in development workflows

## Integration Points

### TypeScript Integration

- Deep integration with TypeScript compiler API
- Access to full type information
- Direct use of TypeScript's parser
- Compatibility with TypeScript projects

### Formatter Integration

- Potential integration with Prettier for formatting
- Unified linting and formatting experience
- Coordinated tooling approach

### Language Server Protocol (LSP)

- Potential editor integration through LSP
- Real-time linting feedback in IDEs
- Language-agnostic editor support

## Comparison with Other Linters

### vs. ESLint

| Aspect | ESLint | Flint |
|--------|--------|-------|
| Language | JavaScript | TypeScript |
| Type-Aware | Limited | Full TypeScript integration |
| Performance | Slower on large codebases | Hybrid approach for optimization |
| Configuration | JSON/JS | Type-safe JavaScript |
| Plugins | Separate npm packages | Integrated tiers |
| Maturity | Production-ready | Experimental |

### vs. Biome

| Aspect | Biome | Flint |
|--------|-------|-------|
| Language | Rust | TypeScript + optional native |
| Contributor Accessibility | Lower | Higher |
| Performance | Very fast | Optimized hybrid |
| Formatter Included | Yes | Planned |
| Linter + Formatter | Yes | Yes (planned) |
| Customizability | Limited | High |

### vs. Oxlint

| Aspect | Oxlint | Flint |
|--------|--------|-------|
| Language | Rust | TypeScript + optional native |
| ESLint Compatible | Partial | Not directly |
| Performance | Extremely fast | Optimized hybrid |
| Community Contributions | Limited | Encouraged |
| Maturity | Established | Early experimental |

## Technical Implementation

### Plugin Interface

Plugins in Flint:
- Implement a well-defined TypeScript interface
- Can be written in any language
- Communicate with core through defined protocols
- Maintain version compatibility

### Rule Definition

Rules follow a consistent structure:
```typescript
interface LintRule {
  name: string;
  description: string;
  severity: 'error' | 'warning';
  create: (context: RuleContext) => RuleListeners;
}
```

### Type Information Flow

1. TypeScript parses the source code
2. Type checker generates type information
3. Rules access both AST and type information
4. Rules report violations with detailed context
5. Core formats and outputs results

## Evolution and Future

### Phase 1: Foundation
- Core architecture definition
- Initial rule set
- Configuration system
- Basic plugin support

### Phase 2: Optimization
- Performance tuning
- Caching system implementation
- Native plugin examples
- Production hardening

### Phase 3: Maturity
- Full LSP integration
- Comprehensive rule library
- Community plugin ecosystem
- Stable release

## Why This Architecture?

Flint's design addresses fundamental questions:

1. **Is hybrid better?** - Can we get both community accessibility and native performance?
2. **Does type-safety help?** - Can better configuration reduce user errors?
3. **Is tiered organization better?** - Can rule organization improve developer experience?
4. **Can tooling unify?** - Can integrated formatters and diagnostics simplify CI?

The experimental nature of Flint allows testing these hypotheses in practice, learning whether this approach represents an actual improvement or validates why existing tools are designed differently.

---

**Related Documentation**:
- [Configuration Guide](./configuration.md)
- [Rules System](./rules.md)
- [Plugin Development](./plugins.md)

---

# Flint Configuration Guide

## Source: https://flint.fyi

## Overview

Flint's configuration system is designed with type safety and developer experience in mind. Unlike JSON-based configuration systems, Flint uses type-safe JavaScript configuration files that provide IDE autocomplete, type checking, and automatic edge case handling.

**Status**: Configuration system is currently under development as Flint is in early experimental stages.

## Configuration Philosophy

### Problems with Existing Configuration Systems

Traditional linters face configuration challenges:

**JSON Configuration**
- No IDE support or autocomplete
- No type validation
- Prone to user errors
- Limited flexibility
- Hard to compose

**JavaScript Configuration**
- More flexible but requires manual validation
- Error-prone with complex edge cases
- No standard structure
- Users must handle parsing and validation

### Flint's Approach

Type-safe JavaScript configuration:

```typescript
// flint.config.ts - Fully type-safe
export default {
  rules: {
    'rule-name': 'error',
    'another-rule': {
      severity: 'warn',
      option: true
    }
  },
  plugins: [
    '@flint.fyi/react',
    '@flint.fyi/performance'
  ]
}
```

**Benefits**:
- Full IDE autocomplete for all options
- Type validation at configuration time
- Cleaner, more readable syntax
- Composable and flexible
- Automatic edge case handling

## Configuration File

### File Location

Configuration is typically defined in the project root:
- `flint.config.ts` - TypeScript (recommended)
- `flint.config.js` - JavaScript (if TS not available)
- `flint.config.mts` - ES modules

### Minimal Configuration

```typescript
// flint.config.ts
export default {}
```

This uses Flint's defaults:
- All core plugins enabled
- Recommended rule settings
- Standard output formatting

## Core Configuration Options

### Rules Configuration

#### Disabling a Rule

```typescript
export default {
  rules: {
    'rule-name': 'off'
  }
}
```

#### Changing Severity

```typescript
export default {
  rules: {
    'rule-name': 'warn',  // 'error' or 'warn'
  }
}
```

#### Rule-Specific Options

```typescript
export default {
  rules: {
    'rule-name': {
      severity: 'error',
      // Rule-specific configuration
      option1: true,
      option2: false,
      option3: 'value'
    }
  }
}
```

### Plugins Configuration

#### Including Plugins

```typescript
export default {
  plugins: [
    '@flint.fyi/react',
    '@flint.fyi/performance',
    '@flint.fyi/node'
  ]
}
```

#### Plugin-Specific Configuration

```typescript
export default {
  plugins: [
    {
      name: '@flint.fyi/react',
      config: {
        hookRulesOfDeps: true,
        reactVersion: '18'
      }
    }
  ]
}
```

## File Patterns and Overrides

### Specifying File Patterns

```typescript
export default {
  // Global rules apply to all files
  rules: {
    'rule-1': 'error'
  },

  // Override rules for specific file patterns
  overrides: [
    {
      files: ['**/*.test.ts', '**/*.spec.ts'],
      rules: {
        'no-console': 'off'
      }
    },
    {
      files: ['src/browser/**/*'],
      plugins: ['@flint.fyi/browser']
    }
  ]
}
```

### File Pattern Syntax

Supports glob patterns:
- `**/*.ts` - All TypeScript files
- `src/**/*` - All files in src directory
- `*.json` - JSON files in root
- `{*.ts,*.tsx}` - Multiple extensions

## Type-Safe Configuration Benefits

### IDE Support

Modern IDEs provide:
- **Autocomplete**: Type hints for all configuration options
- **Type Checking**: Errors for invalid configurations
- **Documentation**: Built-in help and descriptions
- **Quick Navigation**: Jump to definitions and references

### Configuration Validation

The TypeScript compiler validates:
- Correct option names
- Valid values for options
- Type compatibility
- Missing required fields

### Development Experience

Benefits during development:
- Immediate feedback on configuration errors
- Less time debugging configuration issues
- Self-documenting configuration
- Easy refactoring with IDE support

## Advanced Configuration

### Merging Configurations

```typescript
import baseConfig from './flint.config.base'

export default {
  ...baseConfig,
  rules: {
    ...baseConfig.rules,
    'custom-rule': 'error'
  }
}
```

### Conditional Configuration

```typescript
const isDevelopment = process.env.NODE_ENV === 'development'

export default {
  rules: {
    'rule-name': isDevelopment ? 'warn' : 'error'
  }
}
```

### Environment-Specific Configuration

```typescript
export default {
  rules: {
    // Common rules
    'no-console': 'warn'
  },
  overrides: [
    {
      files: ['src/**/*.ts'],
      rules: {
        'strict-mode': 'error'
      }
    },
    {
      files: ['scripts/**/*.ts'],
      rules: {
        'strict-mode': 'off'
      }
    }
  ]
}
```

## Plugin Configuration

### Core Plugins

Core plugins are always available and can be configured:

```typescript
export default {
  rules: {
    // Configure core rules
    'json-valid': 'error',
    'markdown-valid': 'error',
    'yaml-valid': 'error'
  }
}
```

### Adding Focused Plugins

```typescript
export default {
  plugins: [
    '@flint.fyi/react',      // React best practices
    '@flint.fyi/node',       // Node.js best practices
    '@flint.fyi/performance' // Performance rules
  ]
}
```

### Adding Incubator Plugins

```typescript
export default {
  plugins: [
    '@flint.fyi/next',  // Next.js specific
    '@flint.fyi/vitest' // Vitest testing
  ]
}
```

## Disable Comments

### File-Level Disables

Disable a rule for an entire file:

```typescript
// @flint-disable rule-name
// File content...
```

### Line-Level Disables

Disable a rule for a single line:

```typescript
const x: any = 'something'; // @flint-disable-line rule-name
```

Disable multiple rules:

```typescript
// @flint-disable rule-1 rule-2 rule-3
// Multiple lines can be affected...
```

## Formatting and Output

### Output Options

```typescript
export default {
  output: {
    format: 'json' | 'text' | 'html',
    // ... more options
  }
}
```

### Interactive Mode

```typescript
export default {
  output: {
    interactive: true  // Allow interactive fixing
  }
}
```

## Performance Configuration

### Caching

Type-aware caching is automatically enabled:

```typescript
export default {
  cache: {
    enabled: true,        // Enable caching (default)
    directory: '.flint'   // Cache directory
  }
}
```

### Parallel Processing

```typescript
export default {
  performance: {
    workers: 4  // Number of parallel workers
  }
}
```

## Extending Configurations

### Shareable Configurations

Create a base configuration to share across projects:

```typescript
// shared-flint-config.ts
export default {
  rules: {
    'no-console': 'warn',
    'no-debugger': 'error'
  },
  plugins: [
    '@flint.fyi/react'
  ]
}
```

### Using Shared Configurations

```typescript
import baseConfig from '@company/flint-config'

export default {
  ...baseConfig,
  rules: {
    ...baseConfig.rules,
    'custom-rule': 'error'
  }
}
```

## Migration from ESLint

### Similar Concepts

| ESLint | Flint |
|--------|-------|
| `.eslintrc.json` | `flint.config.ts` |
| `rules` | `rules` |
| `extends` | `...config` or imports |
| `overrides` | `overrides` |
| `plugins` | `plugins` |

### Key Differences

1. **Type Safety**: Flint configs are type-checked
2. **Language**: TypeScript instead of JSON
3. **Syntax**: No extends, use JavaScript imports instead
4. **Plugins**: Different plugin naming and interface
5. **Rules**: Different rule names and options

## Troubleshooting Configuration

### Rule Not Being Applied

1. Check rule is enabled in configuration
2. Verify file matches pattern in `overrides`
3. Check plugin is listed in `plugins`
4. Confirm rule name is correct

### Conflicting Rules

If rules conflict:
1. Disable one rule for the file type
2. Use `overrides` for different settings
3. Check plugin documentation for interactions

### Configuration Not Loaded

Ensure:
1. File is named `flint.config.ts` (or `.js`)
2. File is in project root
3. File has `export default` statement
4. TypeScript syntax is valid

## Best Practices

### Configuration Organization

1. **Keep it simple**: Start with defaults, add only needed config
2. **Use TypeScript**: Take advantage of type safety
3. **Document complex rules**: Add comments for non-obvious settings
4. **Organize overrides**: Group related overrides together
5. **Version control**: Include config in git

### Rule Configuration Strategy

1. **Start conservative**: More rules can be too strict
2. **Gradually adopt**: Enable rules as team agrees on standards
3. **Use warnings first**: Ease into errors for new rules
4. **Per-file customization**: Use overrides for special cases
5. **Team alignment**: Discuss rules with team before enforcing

### Plugin Selection

1. **Core first**: Enable core rules matching your languages
2. **Pick relevant plugins**: Only include what your project uses
3. **Avoid plugin overload**: Too many rules can be overwhelming
4. **Incubator usage**: Try incubator plugins for emerging tech

## Configuration in CI/CD

### GitHub Actions Example

```yaml
name: Lint
on: [push, pull_request]
jobs:
  flint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm install
      - run: npx flint
```

### Pre-commit Hook

```bash
#!/bin/bash
# .husky/pre-commit
npx flint --staged
```

## Environment Variables

Configuration can use environment variables:

```typescript
export default {
  rules: {
    'rule-name': process.env.STRICT_MODE ? 'error' : 'warn'
  }
}
```

Set before running flint:

```bash
STRICT_MODE=true flint
```

## See Also

- [Rules System](./rules.md)
- [Architecture Overview](./architecture.md)
- [Getting Started](./index.md)

---

**Note**: Configuration system is under active development. Details may change as Flint matures.

---

# Contributing to Flint

## Source: https://github.com/flint-fyi/flint

Flint is an open-source project that welcomes contributions from the community. This guide explains how to get involved.

## Code of Conduct

All contributors are expected to follow the [Contributor Covenant Code of Conduct](https://github.com/flint-fyi/flint/blob/main/.github/CODE_OF_CONDUCT.md). We are committed to providing a welcoming and inclusive environment for all contributors.

## How to Contribute

There are many ways to contribute to Flint:

### 1. Report Issues

Found a bug or have a feature request?

- Visit the [GitHub issue tracker](https://github.com/flint-fyi/flint/issues)
- Choose the most appropriate issue template
- Fill out all required fields completely
- Provide clear, detailed information about the issue

Issue templates help categorize contributions:
- **Bug Report**: Report issues you've discovered
- **Feature Request**: Suggest new features or improvements
- **Documentation**: Suggest documentation improvements
- **General Feedback**: Provide general feedback or ideas

### 2. Send Pull Requests

Contributing code is welcome! Here's the process:

#### Before You Start

Look for issues on the tracker that meet these criteria:
- Marked as `status: accepting prs` label
- Not marked as `ai assigned` label
- Have no open PRs already

If this is your first contribution, look for issues also marked with `good first issue`.

**Note**: Flint does not use an issue claiming system. Don't post comments asking permission - if an issue hasn't received a PR yet, you can send one.

#### Steps to Send a PR

1. **Fork the repository**
   ```bash
   gh repo fork flint-fyi/flint
   git clone https://github.com/YOUR_USERNAME/flint
   cd flint
   ```

2. **Create a feature branch**
   ```bash
   git checkout -b feature-description
   # Use a descriptive branch name
   ```

3. **Make your changes**
   - Write clear, focused code
   - Follow the project's code style
   - Add tests for new functionality
   - Update documentation as needed

4. **Commit with conventional commits**
   ```bash
   git commit -m "feat: add new feature"
   git commit -m "fix: resolve bug issue"
   git commit -m "docs: update documentation"
   ```

   PR titles must follow [Conventional Commits](https://www.conventionalcommits.org/):
   - `feat:` for new features
   - `fix:` for bug fixes
   - `docs:` for documentation
   - `test:` for tests
   - `refactor:` for code refactoring
   - `chore:` for maintenance

5. **Push to your fork**
   ```bash
   git push origin feature-description
   ```

6. **Create a Pull Request**
   - Visit your fork on GitHub
   - Click "Create Pull Request"
   - Fill out the PR template completely
   - Include a clear description of changes

7. **Ensure checks pass**
   - GitHub status checks must pass
   - Ask questions in PR comments if unclear
   - Respond to review feedback

8. **Address review feedback**
   ```bash
   # Make requested changes
   git add .
   git commit -m "refactor: address review feedback"
   git push origin feature-description

   # Re-request review
   ```

9. **Merge approval**
   - Once approved, maintainers will merge your PR
   - You don't need to merge it yourself

#### Pull Request Guidelines

- **Keep PRs focused**: Solve one problem per PR
- **Reasonable size**: Smaller PRs are easier to review
- **Good titles**: Use conventional commits format
- **Clear description**: Explain the "why" not just the "what"
- **Tests included**: Add tests for new functionality
- **Passing checks**: Ensure CI passes before requesting review

#### Draft PRs

If your PR isn't ready for review:
1. Click the "Convert to draft" button
2. Draft PRs won't be reviewed
3. Convert back when ready

#### Changeset for User-Facing Changes

If your PR includes user-facing changes:

```bash
pnpm changeset
```

This creates a changeset file that helps with versioning and release notes.

### 3. Improve Documentation

Documentation improvements are always welcome!

- Grammar and clarity fixes
- Adding examples
- Clarifying complex concepts
- Adding missing sections
- Updating outdated information

### 4. Provide Feedback

Share your thoughts and ideas:
- Participate in discussions
- Join the Discord community
- Comment thoughtfully on issues
- Help other contributors

## Development Setup

### Prerequisites

- Node.js 18+ (recommended 20+)
- npm or pnpm
- Git
- A text editor or IDE

### Local Development

See [DEVELOPMENT.md](https://github.com/flint-fyi/flint/blob/main/.github/DEVELOPMENT.md) in the repository for detailed setup instructions.

Basic steps:

```bash
# Clone the repository
git clone https://github.com/flint-fyi/flint
cd flint

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build the project
pnpm build

# Run Flint on itself
pnpm flint
```

## Community

### Join the Community

Connect with other Flint contributors and users:

- **Discord**: https://flint.fyi/discord - Real-time discussion and support
- **GitHub Discussions**: Threaded conversations about features and ideas
- **GitHub Issues**: Report bugs and request features
- **GitHub Releases**: Follow project updates

### Getting Help

If you need help:

1. **Check existing issues**: Your question might be answered there
2. **Ask on Discord**: Real-time help from community members
3. **Create a discussion**: For questions that aren't bug reports
4. **Comment on issues**: Ask for clarification from maintainers

## Contribution Ideas

### Good First Issues

Look for issues marked with these labels:
- `good first issue` - Perfect for newcomers
- `status: accepting prs` - Ready for contributions
- No `ai assigned` label - Not already assigned

### Areas for Contribution

- **Bug fixes**: Fix known issues
- **Rule additions**: Add new linting rules
- **Plugin development**: Create new plugins
- **Documentation**: Improve guides and examples
- **Testing**: Increase test coverage
- **Performance**: Optimize slow operations
- **Accessibility**: Improve IDE and tooling support

### Example Contributions

Examples of valuable contributions:

1. **Add a new rule** to an existing plugin
2. **Create a new focused plugin** for a popular framework
3. **Improve rule documentation** with more examples
4. **Add missing tests** for existing functionality
5. **Fix performance issues** identified in PRs
6. **Improve error messages** for clarity
7. **Add configuration examples** to documentation
8. **Create example projects** showing Flint usage

## Code Style and Standards

### TypeScript

Flint is written in strict TypeScript:
- Enable strict mode
- No `any` types without explicit justification
- Full type annotations
- Comprehensive type coverage

### Testing

- Write tests for new features
- Update tests for changed behavior
- Aim for high code coverage
- Use clear, descriptive test names

### Formatting

- Follow ESLint/Prettier conventions
- Run `pnpm format` to auto-format
- Keep line lengths reasonable
- Use meaningful variable names

### Commits

- Keep commits focused and atomic
- Write descriptive commit messages
- One logical change per commit
- Squash merge to main keeps history clean

## Review Process

### What to Expect

1. **Automated checks** run on every push
2. **Maintainer review** within reasonable time
3. **Requested changes** for improvements
4. **Approval** when changes are good
5. **Merge** by maintainer

### Providing Feedback

When reviewing others' code:
- Be respectful and constructive
- Ask questions rather than make demands
- Acknowledge good work
- Suggest improvements with reasoning
- Follow the Code of Conduct

## Emoji Appreciation

When submitting issues or PRs, include an emoji to show you've read the contribution guide. This helps us quickly identify engaged contributors!

The flaming heart emoji (❤️‍🔥) is the project's signature emoji, but any thoughtful emoji works.

## Frequently Asked Questions

### Can I work on an issue that's assigned?

No, assignment indicates an AI is currently working on it. Look for unassigned issues instead.

### Do I need permission to contribute?

No! If an issue is marked `status: accepting prs` and has no open PR, you can send one directly.

### What if I'm stuck?

Ask questions in PR comments or on Discord. Maintainers and community members are happy to help!

### How long does review take?

Review times vary based on maintainer availability and PR complexity. Be patient - all PRs will be reviewed.

### Can I contribute examples or tutorials?

Absolutely! Examples and tutorials are valuable contributions, whether in the repo or elsewhere.

## Recognition

Once your PR is merged:
- Check if you should be added to the contributors table
- Ping the merging maintainer if not added within 24 hours
- Your contribution is acknowledged in release notes

## Financial Support

If you'd like to support Flint financially:

- Visit [Open Collective](https://opencollective.com/flintfyi)
- One-time or recurring donations
- Your contribution helps fund development

## Additional Resources

- **GitHub Repository**: https://github.com/flint-fyi/flint
- **Issue Tracker**: https://github.com/flint-fyi/flint/issues
- **Pull Requests**: https://github.com/flint-fyi/flint/pulls
- **Code of Conduct**: https://github.com/flint-fyi/flint/blob/main/.github/CODE_OF_CONDUCT.md
- **Contributing Guidelines**: https://github.com/flint-fyi/flint/blob/main/.github/CONTRIBUTING.md
- **Development Guide**: https://github.com/flint-fyi/flint/blob/main/.github/DEVELOPMENT.md

## Support the Project

### Ways to Help Beyond Code

- Share Flint with others
- Write blog posts about using Flint
- Create example projects
- Improve documentation
- Test and report bugs
- Provide feedback and ideas
- Participate in discussions
- Help new contributors

## Final Thoughts

Thank you for considering contributing to Flint! Whether it's code, documentation, ideas, or community participation, every contribution helps move the project forward.

The community around Flint is just as important as the code itself. We look forward to collaborating with you!

---

**Remember**: The flaming heart (❤️‍🔥) is our favorite emoji!

---

# Flint - A Modern TypeScript-Focused Linter

## Source: https://flint.fyi

Flint is an experimental, fast TypeScript/JavaScript linter with a hybrid architecture designed to test modern approaches to code linting. The core is written in TypeScript for accessibility, with language-specific plugins able to use native-speed tooling for optimal performance.

## Overview

**Flint** is a fast, friendly linter for JavaScript, TypeScript, and other web ecosystem languages. It's a proof-of-concept exploring novel approaches to linting architecture, configuration, rule organization, and tooling integration.

Created by Josh Goldberg and maintained by open source volunteers, Flint operates independently without corporate backing or funding pressure.

### Current Status

**Important**: Flint is still very early stage and experimental. Not all features have been implemented. The project is in active development and the creators explicitly state: "Don't expect Flint to be ready to alpha test for several months from now, at the earliest."

## Design Philosophy

Flint is built on four core hypotheses about modern linting:

### 1. Hybrid Linting Architecture

Traditional linters typically choose between:
- **JavaScript/TypeScript-based**: Easier to contribute to but slower (like ESLint)
- **Native languages**: Faster but harder for community contributions (like Biome, Oxlint)

Flint combines the best of both worlds:
- **Core framework**: Written in TypeScript for accessibility and ease of contribution
- **Language plugins**: Can be developed in native performance-focused languages for computational efficiency

This approach delegates the most computationally expensive tasks like parsing and type checking to native-speed languages, while keeping the linter framework approachable for contributors.

### 2. Streamlined Configuration System

Rather than forcing users to choose between:
- **Rigid JSON configs**: Limited flexibility and prone to errors
- **JavaScript-based setups**: Complex and error-prone

Flint proposes fully type-safe JavaScript configurations that automatically handle parsing, processing, and other edge case hazards behind-the-scenes. This avoids the pitfalls ESLint users experienced while maintaining flexibility for workspace configurations and plugin composition.

### 3. Comprehensive Built-in Rules

Flint bundles extensive rules directly into the core project across multiple tiers:
- **Core plugins**: Universal rules applicable to any project
- **Focused plugins**: Rules for large areas or specific code styles
- **Incubator plugins**: Area-specific plugins under community governance

The project maintains a reference list of over 1,000 popular lint rules to ensure comprehensive coverage.

### 4. Tooling Coordination

Flint integrates formatters (Prettier) and language diagnostics (TypeScript type errors) into a unified linting experience, reducing CI complexity for development teams. This eliminates the need for separate tool chains and coordinates linting concerns.

## Core Features

### Ergonomic Rule Writing
- Write linting rules in JavaScript or TypeScript
- Access to TypeScript's powerful type system for rule definitions
- Approachable for both users and contributors

### Performance Optimization
- Hybrid architecture balances speed with developer experience
- Type-aware caching for significant performance improvements
- Native-speed parsing and type checking when needed

### Streamlined Configuration
- Flexible, type-safe configuration files
- Automatic edge case handling
- Simplified workspace and plugin composition

### Unified Core
- Popular rules promoted to the core project
- More reliable inclusion and maintenance
- Consistent rule quality and documentation

## Rule Organization

Flint organizes linting rules into three tiers:

### Core Plugins (Included with `flint`)

Rules applicable to any project using their language:

- **JSON** - Rules for linting `.json` files
- **Markdown** - Rules for linting `.md` files containing Markdown
- **PackageJSON** - Rules for linting Node.js `package.json` manifest files
- **TypeScript/JavaScript** - Rules for linting JavaScript and TypeScript code
- **YAML** - Rules for linting `.yaml`/`.yml` files

### Focused Plugins

Plugins for large areas of projects or code styles applicable to many (but not all) Flint users. Available as separate packages under `@flint.fyi/`:

- Browser
- Flint
- JSX
- Node.js
- Performance
- Sorting
- Spelling

### Incubator Plugins

Area-specific plugins that should exist under community governance, but don't yet have a dedicated team. Available as separate packages under `@flint.fyi/`:

- Astro
- Next.js
- Nuxt
- React
- SolidJS
- Vitest
- Vue

## Getting Started

Usage instructions are currently being developed. The planned setup process will involve:

1. Running the `flint` command in an existing project
2. Being prompted about preferred linting areas
3. Automatic configuration file generation
4. Installation of necessary dependencies

**Note**: This feature is not yet implemented as Flint is still in very early development.

## Community and Resources

### Connect with the Community

- **Discord Server**: https://flint.fyi/discord - Active community discussing development and ideas
- **GitHub Issues**: https://github.com/flint-fyi/flint/issues - Report bugs and request features
- **Open Collective**: https://opencollective.com/flintfyi - Support the project financially

### Documentation and References

- **Official Website**: https://flint.fyi
- **Rules Reference**: https://flint.fyi/rules
- **GitHub Repository**: https://github.com/flint-fyi/flint
- **Blog**: https://flint.fyi/blog/

### Related Reading

Flint's design is informed by Josh Goldberg's blog series on linter architecture:

1. [Hybrid Linters: The Best of Both Worlds](https://www.joshuakgoldberg.com/blog/hybrid-linters-the-best-of-both-worlds)
2. [If I Wrote a Linter, Part 1: Architecture](https://www.joshuakgoldberg.com/blog/if-i-wrote-a-linter-part-1-architecture)
3. [If I Wrote a Linter, Part 2: Developer Experience](https://www.joshuakgoldberg.com/blog/if-i-wrote-a-linter-part-2-developer-experience)
4. [If I Wrote a Linter, Part 3: Ecosystem](https://www.joshuakgoldberg.com/blog/if-i-wrote-a-linter-part-3-ecosystem)
5. [If I Wrote a Linter, Part 4: Summary](https://www.joshuakgoldberg.com/blog/if-i-wrote-a-linter-part-4-summary)

## Contributing

Flint welcomes contributions from the community. The project maintains:

- **Contributor Covenant Code of Conduct** - Expected behavior for all contributors
- **Contributing Guidelines** - Process for reporting issues and sending pull requests
- **Development Documentation** - Instructions for local development setup

Contributors should:

1. File or find an issue marked as `status: accepting prs`
2. Send a pull request adhering to conventional commits
3. Add a changeset for user-facing changes using `pnpm changeset`
4. Keep PRs single-purpose and focused
5. Ensure GitHub status checks pass before requesting review

### For First-Time Contributors

Look for issues marked with both:
- `good first issue` label
- `status: accepting prs` label

These are specifically identified as suitable starting points for new contributors.

## Technical Stack

### Core Technology
- **Language**: TypeScript (strict mode)
- **Package Manager**: npm (published as `flint`)
- **Repository**: https://github.com/flint-fyi/flint
- **License**: MIT

### Architecture Highlights
- **Monorepo Structure**: Multiple packages organized for different plugins and tools
- **Type Safety**: Strict TypeScript configuration
- **Plugin System**: Modular architecture supporting core, focused, and incubator plugins
- **Performance**: Hybrid approach with native-speed components where needed

## Success Criteria

Flint's ultimate purpose is experimental validation. Success means either:

1. **Confirming all hypotheses** - Proving this approach creates a fast, straightforward linter that's better than existing solutions
2. **Disproving them** - Validating why existing solutions like ESLint and Biome are designed the way they are

The project explicitly acknowledges it might go nowhere, might show some ideas to be wrong, or might become a real linter. Only time will tell.

## Why Flint Exists

Traditional linters have made compromises:
- ESLint prioritized developer experience over performance
- Biome and Oxlint prioritized performance over community contribution accessibility

Flint explores whether a third way is possible: combining the accessibility of ESLint with the performance of native linters through intelligent architectural choices.

The project tests whether:
- A hybrid approach can deliver both ergonomics and performance
- Type-safe configuration can solve years of ESLint configuration pain points
- Organizing rules by scope improves developer experience
- Unified tooling coordination reduces CI complexity

## Project Statistics

- **Contributors**: 10+ community members
- **NPM Package**: Published as `flint`
- **Repository**: Active development on GitHub
- **Code Quality**: Strict TypeScript

## Frequently Asked Questions

### Is Flint ready to use?

No, Flint is in very early experimental development. The core features are still being designed and implemented. Expect several more months of development before alpha testing.

### Can I contribute?

Yes! Flint actively welcomes contributions. Check the GitHub issues for items marked as `status: accepting prs` and `good first issue` to get started.

### What's the relationship between Flint and ESLint?

Flint is inspired by ESLint's approach but explores different architectural choices. Both projects serve different purposes and audiences. Flint is experimental, while ESLint is a mature, widely-used production tool.

### Will Flint replace ESLint?

Flint's goal is to test novel hypotheses about linting, not necessarily to replace existing tools. It might validate existing approaches or provide alternatives. The success criteria is learning from the experiment, regardless of outcome.

### How can I follow Flint's progress?

- Join the Discord: https://flint.fyi/discord
- Watch the GitHub repository: https://github.com/flint-fyi/flint
- Read the blog: https://flint.fyi/blog/

## Related Tools and Concepts

### Similar Linters
- **ESLint** - JavaScript linter (JavaScript-based, mature)
- **Biome** - JavaScript/TypeScript toolchain (native-speed, monorepo focused)
- **Oxlint** - JavaScript linter (native-speed, high performance)

### Complementary Tools
- **Prettier** - Code formatter (integrated into Flint's vision)
- **TypeScript** - Language and type checker (integrated into rules)

### Concepts Explored
- Hybrid linting architecture
- Type-safe configuration
- Rule tier organization
- Tooling coordination

## License

MIT License - See the GitHub repository for details.

## Credits

- **Creator**: Josh Goldberg
- **Team**: Maintained by open source volunteers
- **Contributors**: 10+ community members actively contributing to the project
- **Location**: Boston, USA

---

**Last Updated**: January 2026
**Source**: https://flint.fyi | https://github.com/flint-fyi/flint

---

# Flint Rules System

## Source: https://flint.fyi/rules

## Overview

Flint organizes linting rules into a tiered system designed to support projects of all sizes and specializations. This structure provides:

- **Accessibility**: Clear categorization helps developers find relevant rules
- **Flexibility**: Projects can adopt just the rules they need
- **Maintainability**: Different tiers have appropriate governance models
- **Growth**: Incubator plugins graduate to focused plugins as they mature

## Rule Tiers

### 1. Core Plugins

**Purpose**: Universal rules applicable to any project

Rules included with Flint by default. Maintained by core team with high quality standards.

#### Core Plugin Categories

##### JSON Plugin
- Validates JSON file structure
- Detects common JSON syntax errors
- Enforces formatting conventions
- File types: `.json`

##### Markdown Plugin
- Validates Markdown syntax
- Enforces consistent formatting
- Detects common Markdown issues
- File types: `.md`, `.markdown`

##### PackageJSON Plugin
- Validates `package.json` structure
- Enforces field completeness
- Detects missing required fields
- Checks dependency consistency
- File type: `package.json`

##### TypeScript/JavaScript Plugin
- Detects common programming mistakes
- Enforces code style conventions
- Identifies performance issues
- Provides type-aware rules
- File types: `.ts`, `.tsx`, `.js`, `.jsx`
- **Type-Aware**: Uses TypeScript compiler API for semantic analysis

##### YAML Plugin
- Validates YAML syntax
- Enforces formatting standards
- Detects common YAML mistakes
- File types: `.yaml`, `.yml`

### 2. Focused Plugins

**Purpose**: Rules for large areas or specific code styles applicable to many projects

Plugins available as separate packages under `@flint.fyi/`. Maintained by dedicated teams with focused expertise.

#### Available Focused Plugins

**@flint.fyi/browser**
- Browser API best practices
- DOM manipulation patterns
- Web platform compatibility
- Recommended for browser-focused JavaScript/TypeScript

**@flint.fyi/flint**
- Flint-specific best practices
- Rules for working with Flint itself
- Plugin development guidelines
- Recommended for Flint contributors and plugin authors

**@flint.fyi/jsx**
- JSX syntax and patterns
- React component best practices
- JSX-specific performance issues
- Recommended for React projects

**@flint.fyi/node**
- Node.js API best practices
- Server-side patterns
- Node.js compatibility
- Recommended for Node.js projects

**@flint.fyi/performance**
- Performance anti-patterns
- Optimization opportunities
- Bundle size considerations
- Recommended for performance-critical projects

**@flint.fyi/sorting**
- Consistent import ordering
- Object key organization
- List sorting conventions
- Recommended for projects with formatting standards

**@flint.fyi/spelling**
- Spell checking for comments and strings
- Terminology consistency
- Documentation quality
- Recommended for projects with high documentation standards

### 3. Incubator Plugins

**Purpose**: Area-specific plugins that should exist under community governance

Plugins available as separate packages under `@flint.fyi/`. Maintained by community contributors, designed to eventually graduate to focused plugins.

#### Available Incubator Plugins

**@flint.fyi/astro**
- Astro-specific best practices
- Component patterns
- Performance optimization
- For Astro projects

**@flint.fyi/next**
- Next.js specific rules
- App Router conventions
- Next.js best practices
- For Next.js projects

**@flint.fyi/nuxt**
- Nuxt.js specific rules
- Composition API patterns
- Nuxt conventions
- For Nuxt projects

**@flint.fyi/react**
- React-specific best practices
- Hooks rules
- Component patterns
- For React projects

**@flint.fyi/solidjs**
- Solid.js specific rules
- Reactivity patterns
- Component best practices
- For SolidJS projects

**@flint.fyi/vitest**
- Vitest testing best practices
- Test structure conventions
- Assertion patterns
- For Vitest test files

**@flint.fyi/vue**
- Vue.js specific rules
- Single-file component patterns
- Vue conventions
- For Vue projects

## Rule Reference

### Rule Properties

Each rule in Flint has the following properties:

- **Name**: Unique identifier for the rule (e.g., `no-unused-variables`)
- **Description**: Human-readable explanation of what the rule checks
- **Severity**: Error level - `error` (blocks build) or `warning` (reported but non-blocking)
- **Type**: Detection category (code quality, performance, style, etc.)
- **Fixable**: Whether the rule can automatically fix issues
- **Configuration**: Optional settings to customize rule behavior
- **Documentation**: Detailed explanation and examples

### Rule Coverage

Flint maintains a reference of over 1,000 popular linting rules from various sources. The project uses this reference to ensure comprehensive coverage across:

- General JavaScript/TypeScript rules
- Framework-specific best practices
- Performance and optimization rules
- Security and vulnerability detection
- Code style and formatting rules
- Documentation and comment quality

## How Rules Work

### Rule Execution Flow

```
Source Code File
    ↓
Parser (TypeScript AST)
    ↓
Type Checker (if applicable)
    ↓
Rule Engine
    ├─→ Matches rule conditions?
    ├─→ Rule callback triggered
    ├─→ Reports violation(s)
    └─→ Generates fix(es) if applicable
    ↓
Formatted Results
```

### Type-Aware Rules

Rules in the TypeScript/JavaScript core plugin have access to:
- Full TypeScript type information
- Semantic meaning of code, not just syntax
- Type relationships and flow
- Better detection of logical issues

Example: A rule can understand that a function parameter has type `string` and flag attempts to use it as a number, not just detect syntax errors.

### Configurable Rules

Many rules support configuration options:

```typescript
// Example: configure rule behavior
rules: {
  'no-console': {
    severity: 'warn',
    allowedMethods: ['error', 'warn']
  }
}
```

## Rule Configuration

### Per-Rule Configuration

Rules can be configured individually in `flint.config.ts`:

```typescript
export default {
  rules: {
    'rule-name': {
      severity: 'error' | 'warning',
      // rule-specific options...
    }
  }
}
```

### Plugin-Level Configuration

Plugins can be configured with settings:

```typescript
export default {
  plugins: [
    {
      plugin: '@flint.fyi/performance',
      config: {
        // plugin-specific options...
      }
    }
  ]
}
```

### Enabling/Disabling Rules

Rules can be enabled, disabled, or configured per file:

```typescript
// Disable specific rule for this file
// @flint-disable rule-name

code here
```

## Rule Categories

### Code Quality Rules
- Detect common programming mistakes
- Find potential bugs
- Identify unreachable code
- Flag logical errors

Examples: unused variables, unreachable code, type mismatches

### Performance Rules
- Identify performance anti-patterns
- Suggest optimization opportunities
- Flag inefficient algorithms
- Warn about bundle size impact

Examples: unnecessary re-renders, inefficient DOM access

### Style Rules
- Enforce consistent code style
- Maintain readability conventions
- Ensure formatting consistency
- Promote team standards

Examples: naming conventions, indentation, quotes

### Security Rules
- Detect security vulnerabilities
- Prevent unsafe patterns
- Identify injection risks
- Flag potential exploits

Examples: unsafe DOM operations, eval usage

### Documentation Rules
- Check comment quality
- Enforce documentation standards
- Validate JSDoc comments
- Ensure code clarity

Examples: missing documentation, typos in comments

## Best Practices for Rules

### For Users

1. **Start with core rules**: These are most universally applicable
2. **Add focused plugins for your use case**: Browser, Node, React, etc.
3. **Consider incubator plugins**: For framework-specific rules
4. **Customize as needed**: Adjust severity and configuration
5. **Keep rules focused**: Avoid enabling too many rules at once

### For Plugin Authors

1. **Follow consistent patterns**: Match Flint's rule structure
2. **Document thoroughly**: Include examples and rationale
3. **Provide configuration options**: Allow customization
4. **Keep rules focused**: One concern per rule
5. **Include fixes when possible**: Automate remediation where safe

## Rule Composition

Rules can depend on or build upon each other:

- Core rules provide baseline checks
- Focused plugins extend with specialized knowledge
- Incubator plugins test new ideas
- Custom rules can extend any of the above

This allows projects to compose exactly the rule set they need.

## Future Rule Development

The Flint project:

1. **Monitors popular ESLint rules**: Identifies commonly used patterns
2. **Reviews community requests**: Incorporates user needs
3. **Evaluates new patterns**: Tests emerging best practices
4. **Promotes successful rules**: Moves rules from incubator → focused → core based on community adoption

## Rule Statistics

Current rule categories include:
- **Core rules**: ~40+ across JSON, Markdown, YAML, JavaScript/TypeScript
- **Focused plugins**: ~100+ rules across specialized areas
- **Incubator plugins**: Growing collection of framework-specific rules

## Relationship with ESLint Rules

While Flint doesn't aim to be a direct ESLint replacement, many Flint rules are inspired by popular ESLint rules. The project:

- Studies successful ESLint rules
- Adapts patterns that work well
- Improves on rules with confusing configuration
- Adds type-aware versions of semantic rules
- Creates rules specific to Flint's architecture

## Getting More Information

- **Rules Reference**: https://flint.fyi/rules
- **GitHub Discussions**: Community discussions about specific rules
- **Discord**: Real-time discussion with maintainers
- **Blog Posts**: Deep dives into rule design decisions

---

**Related Documentation**:
- [Architecture Overview](./architecture.md)
- [Configuration Guide](./configuration.md)
- [Getting Started](./index.md)