Skip to content

thai-lint

License: MIT Python 3.11+ Tests Coverage Documentation Status

The AI Linter - Enterprise-ready linting and governance for AI-generated code across multiple languages.

Welcome

thai-lint is a modern, enterprise-ready multi-language linter designed specifically for AI-generated code. It focuses on common mistakes and anti-patterns that AI coding assistants frequently introduce—issues that existing linters don't catch or don't handle consistently across languages.

Why thai-lint?

We're not trying to replace the wonderful existing linters like Pylint, ESLint, or Ruff. Instead, thai-lint fills critical gaps:

  • AI-Specific Patterns: AI assistants have predictable blind spots (excessive nesting, magic numbers, SRP violations) that traditional linters miss
  • Cross-Language Consistency: Detects the same anti-patterns across Python, TypeScript, and JavaScript with unified rules
  • No Existing Solutions: Issues like excessive nesting depth, file placement violations, and cross-project code duplication lack comprehensive multi-language detection
  • Governance Layer: Enforces project-wide structure and organization patterns that AI can't infer from local context

thai-lint complements your existing linting stack by catching the patterns AI tools repeatedly miss.

Features

Core Capabilities

  • File Placement Linting - Enforce project structure and organization
  • Magic Numbers Linting - Detect unnamed numeric literals that should be constants
  • Method Property Linting - Detect methods that should be @property decorators
  • Nesting Depth Linting - Detect excessive code nesting with AST analysis
  • Performance Linting - Detect O(n^2) patterns in loops (string concat, regex)
  • SRP Linting - Detect Single Responsibility Principle violations
  • DRY Linting - Detect duplicate code across projects
  • Collection Pipeline Linting - Detect for loops with embedded filtering
  • Stringly-Typed Linting - Detect string patterns that should use enums
  • Pluggable Architecture - Easy to extend with custom linters
  • Multi-Language Support - Python, TypeScript, JavaScript, and more
  • Flexible Configuration - YAML/JSON configs with pattern matching
  • 5-Level Ignore System - Repo, directory, file, method, and line-level ignores

Deployment Modes

  • CLI Mode - Full-featured command-line interface
  • Library API - Python library for programmatic integration
  • Docker Support - Containerized deployment for CI/CD

Enterprise Features

  • Performance - <100ms for single files, <5s for 1000 files
  • Type Safety - Full type hints and MyPy strict mode
  • Test Coverage - 90% coverage with 296+ tests
  • CI/CD Ready - Proper exit codes and JSON output
  • Comprehensive Docs - Complete documentation and examples

Installation

From PyPI

pip install thailint

From Source

# Clone repository
git clone https://github.com/be-wise-be-kind/thai-lint.git
cd thai-lint

# Install dependencies
pip install -e ".[dev]"

With Docker

# Pull from Docker Hub
docker pull washad/thailint:latest

# Run CLI
docker run --rm washad/thailint:latest --help

Quick Start

CLI Mode

# Check file placement
thailint file-placement .

# Check for magic numbers
thailint magic-numbers src/

# Check nesting depth
thailint nesting src/

# Check for duplicate code
thailint dry .

# Check for embedded filtering patterns
thailint pipeline src/

# Check for performance anti-patterns
thailint perf src/

# Check for stringly-typed patterns
thailint stringly-typed src/

# With config file
thailint dry --config .thailint.yaml src/

# JSON output for CI/CD
thailint dry --format json src/

See the Quick Start Guide for a complete walkthrough.

Library Mode

from src import Linter

# Initialize linter
linter = Linter(config_file='.thailint.yaml')

# Lint directory
violations = linter.lint('src/', rules=['file-placement'])

# Process results
if violations:
    for v in violations:
        print(f"{v.file_path}: {v.message}")

Available Linters

File Placement Linter

Enforce project structure and organization rules.

Magic Numbers Linter

Detect unnamed numeric literals that should be named constants.

Method Property Linter

Detect methods that should be @property decorators.

Nesting Depth Linter

Detect deeply nested code that reduces readability.

Performance Linter

Detect O(n^2) performance anti-patterns: string concatenation and regex compilation in loops.

SRP Linter

Detect Single Responsibility Principle violations in classes.

DRY Linter

Detect duplicate code blocks across your project.

Collection Pipeline Linter

Detect for loops with embedded filtering that should use collection pipelines.

Stringly-Typed Linter

Detect string-based type patterns that should use enums or typed alternatives.

File Header Linter

Enforce comprehensive documentation headers across all source files.

Lazy Ignores Linter

Detect unjustified linting suppressions (noqa, type: ignore, etc.) that lack proper documentation.

Improper Logging Linter

Detect improper logging patterns: print/console statements and conditional verbose guards that should use proper logging configuration.

Deprecated alias for Improper Logging Linter. See Improper Logging Linter.

Stateless Class Linter

Detect classes without state that should be module-level functions.

LBYL Linter

Detect "Look Before You Leap" anti-patterns that should use EAFP (try/except).

Documentation

Support

License

MIT License - see LICENSE file for details.