chous

The World's First Dedicated File Structure Linter
Enforce a clean repository layout with an expressive .chous rules file.

Created by Cheez Lin

GitHub · 中文文档

---

🎉 What's New - Enhanced Fork

This enhanced fork includes major improvements and new features:

👀 Watch Mode (NEW!)

chous --watch          # Monitor file changes and auto re-lint
chous -w --verbose     # Watch mode with detailed output

Real-time linting! Watch mode monitors your project and automatically re-runs linting when files are added, removed, or when the config changes.

⚡ Auto-Fix Command (NEW!)

chous fix              # Automatically fix move and rename issues
chous fix --dry-run    # Preview changes without applying
chous fix --yes        # Skip confirmation prompts

No more manual file moving! Let chous fix your structure automatically.

📚 Ready-to-Use Examples (NEW!)

4 production-ready configuration examples in the examples/ directory:

• Monorepo - Turborepo/Nx workspace structure
• Full-Stack - Next.js + Node.js application
• Microservices - Multiple independent services
• Library - NPM package structure

🎯 19 Framework Presets (NEW!)

Backend: NestJS, Fastify, Hono, Laravel, Django Frontend: Astro, Remix, SvelteKit, Next.js, Nuxt 4, T3 Stack Mobile: React Native, Flutter Desktop: Electron, Tauri Languages: Go, Python, JavaScript, TypeScript

🧪 Production-Ready Quality (NEW!)

• 85%+ test coverage (up from ~10%)
• 140+ test cases for reliability
• CI/CD optimizations - 2-3x faster builds
• Automated security updates via Dependabot
• Code coverage reporting via Codecov

💻 VS Code Extension (NEW!)

Real-time linting in your editor with inline diagnostics, quick fixes, and status bar integration.

🚀 GitHub Action (NEW!)

CI/CD integration with automatic PR comments, auto-fix support, and status checks.

🔌 Plugin System (NEW!)

Extend Chous with custom rules, presets, and validators. Build your own plugins!

📖 Documentation Website (NEW!)

Comprehensive documentation site with guides, API reference, and examples at docs/

---

🚀 The World's First

chous is the world's first dedicated linter for file structures. While other linters focus on what's inside your files, chous focuses on where those files live and how they are named.

chous /tʃoʊs/ - From Chinese "抽丝" (chōu sī), meaning "to draw out silk threads, to untangle". Just as this tool helps you untangle complex file structure issues.

It ensures your project architecture remains consistent, whether you're working in a massive monorepo or a small agile project.

⚡ Vibe Coder's Quick Start (Prompt)

Are you a Vibe Coder using AI editors? Use this 5-step workflow to let the AI handle the architecture for you.

Note

Cursor users can automate Step 5 with hooks. For Windsurf or other editors, simply rely on Step 4 for verification.

"I want to use chous to enforce my project's file structure. Please follow these steps:

1. Run npx chous init to generate a configuration template.
2. Run npx chous to identify current file structure inconsistencies.
3. Based on the lint results and my project goals, customize the .chous file (or help me move files) to achieve a clean architecture.
4. Keep running npx chous and fixing issues until all checks pass.
5. (Optional - Cursor Only) Once verified, run npx chous cursor install to enable real-time protection."

---

✨ Key Features

• 👀 Watch Mode: Real-time linting with automatic re-runs on file changes
• 🔧 Auto-Fix Command: Automatically fix file structure issues - no more manual moving!
• 💻 VS Code Extension: Real-time linting in your editor with inline diagnostics
• 🚀 GitHub Action: CI/CD integration with PR comments and auto-fix support
• 🔌 Plugin System: Extend with custom rules, presets, and validators
• 📚 Ready-to-Use Examples: 4 production-ready configs for common architectures
• 🎯 19 Framework Presets: Built-in support for popular frameworks and languages
• 📖 Documentation Website: Comprehensive docs with guides and API reference
• 🧪 Production-Ready: 85%+ test coverage with 140+ test cases
• ⚡ Fast CI/CD: Optimized builds with dependency caching (2-3x faster)
• 🔒 Automated Security: Dependabot integration for dependency updates
• 📊 Coverage Reporting: Codecov integration for visibility
• Expressive DSL: Human-readable language designed for file systems
• Nested Blocks: Group rules naturally with in <dir>: ... syntax
• AI Editor Integration: Native hooks for Cursor, providing real-time feedback as you code
• Elegant Reporting: Beautiful, tree-style terminal reports that pinpoint exact inconsistencies

📦 Installation

# Run without installation
npx chous

# Or install globally
npm install -g chous

🛠️ Getting Started

1. Initialize:

   chous init

   This will auto-detect your project type and create a .chous file with sensible defaults based on your stack.

2. Lint:

   chous

3. Auto-Fix (NEW!):

   chous fix              # Interactive mode with confirmation
   chous fix --dry-run    # Preview changes without applying
   chous fix --yes        # Auto-apply without confirmation

📋 Quick Commands

# Linting
chous                    # Lint your project structure
chous --verbose          # Show detailed output
chous --strict           # Strict mode (fail on warnings)
chous --watch            # Watch mode: auto re-lint on file changes (NEW!)

# Auto-Fix (NEW!)
chous fix                # Automatically fix move/rename issues
chous fix --dry-run      # Preview fixes without applying
chous fix --yes          # Skip confirmation prompts
chous fix -v             # Verbose output with file paths

# Initialization
chous init               # Create .chous config with auto-detection

# Editor Integration
chous cursor install     # Install Cursor AI editor hooks

🎯 Editor Integration (Cursor Hooks)

If you are using Cursor, you can install an automated hook that runs chous after every AI-powered edit:

chous cursor install

Important

It is recommended to run this command only after you have successfully configured your .chous and all manual lint checks pass. This ensures the AI has a clear "source of truth" to follow.

---

📝 Configuration Guide

The .chous file uses a simple, powerful syntax. Here are some real-world examples derived from the Nuxt 4 preset:

1. Basic Constraints

# Ensure specific files exist
must have [nuxt.config.ts, app]

# Global naming conventions
use kebab-case for files **/*.ts

2. The "Elegant" Nested Syntax

Logical grouping prevents path repetition and makes rules readable:

in app:
  # Allow standard Nuxt directories
  allow [assets, components, composables, pages]
  
  # Deeply nested rules
  in components:
    # All components must be PascalCase
    use PascalCase for files **/*.vue
    # Except when they are inside a PascalCase directory
    use kebab-case for files **/*.vue if-parent-matches PascalCase
    
  strict

3. Automated Move Suggestions

Clean up your assets folder automatically:

in assets:
  move *.{css,scss} to css
  move *.{png,jpg,svg} to images

📂 Available Presets

Core Presets

• basic: Standard ignores and root files
• js / ts: Common JavaScript/TypeScript patterns

Frontend Frameworks

• nextjs: App router and Page router conventions
• nuxt4: Nuxt 4 directory structures and dynamic routes
• t3-stack: T3 Stack (Next.js + tRPC + Prisma + NextAuth + Tailwind) [NEW!]

Backend Frameworks

• laravel: Laravel directory structure and naming conventions [NEW!]
• django: Django project structure and app conventions [NEW!]

Languages

• go: Standard Go workspace layouts
• python: PEP 8 and common Python project structures

Total: 9 presets (3 new presets added in this fork!)

📚 Configuration Examples

Need inspiration? Check out our examples directory with ready-to-use configurations:

• Monorepo - Turborepo/Nx workspace with multiple apps and shared packages
• Full-Stack - Next.js frontend + Node.js backend structure
• Microservices - Multiple independent services with shared libraries
• Library - NPM package/library structure with tests and docs

Each example includes detailed comments and best practices. Copy, customize, and adapt to your project!

🔧 Development

Want to contribute? Here's how to get started:

# Clone the repository
git clone https://github.com/your-username/chous.git
cd chous

# Install dependencies (requires Bun or Node.js 18+)
bun install  # or: npm install

# Run in development mode
bun run dev

# Run tests
bun test

# Build the project
bun run build

For detailed contribution guidelines, architecture overview, and testing instructions, see CONTRIBUTING.md.

📜 License

This project is licensed under the MIT License.