Skip to content

QUICK-START.md

Latest commit

 

History

History
139 lines (109 loc) · 3.5 KB

QUICK-START.md

File metadata and controls

139 lines (109 loc) · 3.5 KB

Quick Start Guide

🚀 Get Started in 5 Minutes

Step 1: Copy the Files

# Create the validation directory
mkdir -p scripts/validation

# Copy all validation scripts
cp scripts/validation/*.js scripts/validation/

# Copy the git hooks configuration
cp lefthook.yml ./

Step 2: Install lefthook

# Install globally (recommended)
npm install -g lefthook

# Or with yarn
yarn global add lefthook

# Or with pnpm
pnpm add -g lefthook

Step 3: Set up Git Hooks

# Install lefthook in your repository
lefthook install

Step 4: Test the Setup

# Make a test commit to see the guardrails in action
git add .
git commit -m "test: testing guardrails setup"

🎯 What Happens Next

On Every Commit

The guardrails will automatically check:

  • ✅ Type safety (no unsafe as casts)
  • ✅ Import patterns (no barrel files, proper aliases)
  • ✅ File complexity (reasonable file sizes)
  • ✅ Documentation (JSDoc on functions)
  • ✅ Directory structure (clean architecture)
  • ✅ Security (no hardcoded secrets)

If Issues Are Found

The commit will be blocked with helpful error messages:

❌ COMMIT BLOCKED: Found 'as' type cast violations!

📁 src/components/UserProfile.tsx:
  Line 15: as any
    const user = response.data as any;

💡 Replace 'as' casts with proper type guards or type predicates

🔧 Customize for Your Project

Adjust Limits (Optional)

Edit scripts/validation/check-file-complexity.js:

const COMPLEXITY_LIMITS = {
  lines: 300,        // Reduce from 500 if you prefer smaller files
  functions: 10,     // Reduce from 15 if you prefer fewer functions per file
  dependencies: 15,  // Reduce from 20 if you prefer fewer imports
}

Add Your Own Exclusions (Optional)

Edit scripts/validation/check-as-casts.js:

const ALLOWED_PATTERNS = [
  /\bas\s+const\b/g,
  /\.test\.(ts|tsx)$/,
  /\.spec\.(ts|tsx)$/,
  // Add your own patterns here
  /your-special-file\.ts$/,
]

🚨 Troubleshooting

"Command not found: lefthook"

# Make sure lefthook is installed globally
npm install -g lefthook

# Or use npx
npx lefthook install

"Too many violations to fix all at once"

# Temporarily bypass checks during development
NODE_ENV=development git commit -m "WIP: fixing violations"

"Some files need exceptions"

Add specific patterns to the validation scripts or use environment variables:

# Skip specific checks
SKIP_COMPLEXITY_CHECK=true git commit -m "feature: new component"

🎯 Next Steps

  1. Read the documentation: Check out WHY-GUARDRAILS.md and EXAMPLES.md
  2. Customize gradually: Start with the defaults, adjust as needed
  3. Train your team: Share the guardrails with your team
  4. Monitor and adjust: Review the guardrails periodically

💡 Pro Tips

For New Projects

  • Start with all guardrails enabled
  • Adjust limits based on your team's preferences
  • Document any exceptions you make

For Existing Projects

  • Start with higher limits and gradually reduce them
  • Fix violations incrementally
  • Use NODE_ENV=development to bypass checks during major refactoring

For Teams

  • Discuss guardrails in team meetings
  • Make sure everyone understands the benefits
  • Review and adjust guardrails as the team grows

That's it! Your project now has AI guardrails that will help maintain code quality automatically. The guardrails will catch issues early and help your team write better code, whether it's generated by AI or written by humans.